File: reference-Core.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 (5611 lines) | stat: -rw-r--r-- 291,647 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
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3928
3929
3930
3931
3932
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978
3979
3980
3981
3982
3983
3984
3985
3986
3987
3988
3989
3990
3991
3992
3993
3994
3995
3996
3997
3998
3999
4000
4001
4002
4003
4004
4005
4006
4007
4008
4009
4010
4011
4012
4013
4014
4015
4016
4017
4018
4019
4020
4021
4022
4023
4024
4025
4026
4027
4028
4029
4030
4031
4032
4033
4034
4035
4036
4037
4038
4039
4040
4041
4042
4043
4044
4045
4046
4047
4048
4049
4050
4051
4052
4053
4054
4055
4056
4057
4058
4059
4060
4061
4062
4063
4064
4065
4066
4067
4068
4069
4070
4071
4072
4073
4074
4075
4076
4077
4078
4079
4080
4081
4082
4083
4084
4085
4086
4087
4088
4089
4090
4091
4092
4093
4094
4095
4096
4097
4098
4099
4100
4101
4102
4103
4104
4105
4106
4107
4108
4109
4110
4111
4112
4113
4114
4115
4116
4117
4118
4119
4120
4121
4122
4123
4124
4125
4126
4127
4128
4129
4130
4131
4132
4133
4134
4135
4136
4137
4138
4139
4140
4141
4142
4143
4144
4145
4146
4147
4148
4149
4150
4151
4152
4153
4154
4155
4156
4157
4158
4159
4160
4161
4162
4163
4164
4165
4166
4167
4168
4169
4170
4171
4172
4173
4174
4175
4176
4177
4178
4179
4180
4181
4182
4183
4184
4185
4186
4187
4188
4189
4190
4191
4192
4193
4194
4195
4196
4197
4198
4199
4200
4201
4202
4203
4204
4205
4206
4207
4208
4209
4210
4211
4212
4213
4214
4215
4216
4217
4218
4219
4220
4221
4222
4223
4224
4225
4226
4227
4228
4229
4230
4231
4232
4233
4234
4235
4236
4237
4238
4239
4240
4241
4242
4243
4244
4245
4246
4247
4248
4249
4250
4251
4252
4253
4254
4255
4256
4257
4258
4259
4260
4261
4262
4263
4264
4265
4266
4267
4268
4269
4270
4271
4272
4273
4274
4275
4276
4277
4278
4279
4280
4281
4282
4283
4284
4285
4286
4287
4288
4289
4290
4291
4292
4293
4294
4295
4296
4297
4298
4299
4300
4301
4302
4303
4304
4305
4306
4307
4308
4309
4310
4311
4312
4313
4314
4315
4316
4317
4318
4319
4320
4321
4322
4323
4324
4325
4326
4327
4328
4329
4330
4331
4332
4333
4334
4335
4336
4337
4338
4339
4340
4341
4342
4343
4344
4345
4346
4347
4348
4349
4350
4351
4352
4353
4354
4355
4356
4357
4358
4359
4360
4361
4362
4363
4364
4365
4366
4367
4368
4369
4370
4371
4372
4373
4374
4375
4376
4377
4378
4379
4380
4381
4382
4383
4384
4385
4386
4387
4388
4389
4390
4391
4392
4393
4394
4395
4396
4397
4398
4399
4400
4401
4402
4403
4404
4405
4406
4407
4408
4409
4410
4411
4412
4413
4414
4415
4416
4417
4418
4419
4420
4421
4422
4423
4424
4425
4426
4427
4428
4429
4430
4431
4432
4433
4434
4435
4436
4437
4438
4439
4440
4441
4442
4443
4444
4445
4446
4447
4448
4449
4450
4451
4452
4453
4454
4455
4456
4457
4458
4459
4460
4461
4462
4463
4464
4465
4466
4467
4468
4469
4470
4471
4472
4473
4474
4475
4476
4477
4478
4479
4480
4481
4482
4483
4484
4485
4486
4487
4488
4489
4490
4491
4492
4493
4494
4495
4496
4497
4498
4499
4500
4501
4502
4503
4504
4505
4506
4507
4508
4509
4510
4511
4512
4513
4514
4515
4516
4517
4518
4519
4520
4521
4522
4523
4524
4525
4526
4527
4528
4529
4530
4531
4532
4533
4534
4535
4536
4537
4538
4539
4540
4541
4542
4543
4544
4545
4546
4547
4548
4549
4550
4551
4552
4553
4554
4555
4556
4557
4558
4559
4560
4561
4562
4563
4564
4565
4566
4567
4568
4569
4570
4571
4572
4573
4574
4575
4576
4577
4578
4579
4580
4581
4582
4583
4584
4585
4586
4587
4588
4589
4590
4591
4592
4593
4594
4595
4596
4597
4598
4599
4600
4601
4602
4603
4604
4605
4606
4607
4608
4609
4610
4611
4612
4613
4614
4615
4616
4617
4618
4619
4620
4621
4622
4623
4624
4625
4626
4627
4628
4629
4630
4631
4632
4633
4634
4635
4636
4637
4638
4639
4640
4641
4642
4643
4644
4645
4646
4647
4648
4649
4650
4651
4652
4653
4654
4655
4656
4657
4658
4659
4660
4661
4662
4663
4664
4665
4666
4667
4668
4669
4670
4671
4672
4673
4674
4675
4676
4677
4678
4679
4680
4681
4682
4683
4684
4685
4686
4687
4688
4689
4690
4691
4692
4693
4694
4695
4696
4697
4698
4699
4700
4701
4702
4703
4704
4705
4706
4707
4708
4709
4710
4711
4712
4713
4714
4715
4716
4717
4718
4719
4720
4721
4722
4723
4724
4725
4726
4727
4728
4729
4730
4731
4732
4733
4734
4735
4736
4737
4738
4739
4740
4741
4742
4743
4744
4745
4746
4747
4748
4749
4750
4751
4752
4753
4754
4755
4756
4757
4758
4759
4760
4761
4762
4763
4764
4765
4766
4767
4768
4769
4770
4771
4772
4773
4774
4775
4776
4777
4778
4779
4780
4781
4782
4783
4784
4785
4786
4787
4788
4789
4790
4791
4792
4793
4794
4795
4796
4797
4798
4799
4800
4801
4802
4803
4804
4805
4806
4807
4808
4809
4810
4811
4812
4813
4814
4815
4816
4817
4818
4819
4820
4821
4822
4823
4824
4825
4826
4827
4828
4829
4830
4831
4832
4833
4834
4835
4836
4837
4838
4839
4840
4841
4842
4843
4844
4845
4846
4847
4848
4849
4850
4851
4852
4853
4854
4855
4856
4857
4858
4859
4860
4861
4862
4863
4864
4865
4866
4867
4868
4869
4870
4871
4872
4873
4874
4875
4876
4877
4878
4879
4880
4881
4882
4883
4884
4885
4886
4887
4888
4889
4890
4891
4892
4893
4894
4895
4896
4897
4898
4899
4900
4901
4902
4903
4904
4905
4906
4907
4908
4909
4910
4911
4912
4913
4914
4915
4916
4917
4918
4919
4920
4921
4922
4923
4924
4925
4926
4927
4928
4929
4930
4931
4932
4933
4934
4935
4936
4937
4938
4939
4940
4941
4942
4943
4944
4945
4946
4947
4948
4949
4950
4951
4952
4953
4954
4955
4956
4957
4958
4959
4960
4961
4962
4963
4964
4965
4966
4967
4968
4969
4970
4971
4972
4973
4974
4975
4976
4977
4978
4979
4980
4981
4982
4983
4984
4985
4986
4987
4988
4989
4990
4991
4992
4993
4994
4995
4996
4997
4998
4999
5000
5001
5002
5003
5004
5005
5006
5007
5008
5009
5010
5011
5012
5013
5014
5015
5016
5017
5018
5019
5020
5021
5022
5023
5024
5025
5026
5027
5028
5029
5030
5031
5032
5033
5034
5035
5036
5037
5038
5039
5040
5041
5042
5043
5044
5045
5046
5047
5048
5049
5050
5051
5052
5053
5054
5055
5056
5057
5058
5059
5060
5061
5062
5063
5064
5065
5066
5067
5068
5069
5070
5071
5072
5073
5074
5075
5076
5077
5078
5079
5080
5081
5082
5083
5084
5085
5086
5087
5088
5089
5090
5091
5092
5093
5094
5095
5096
5097
5098
5099
5100
5101
5102
5103
5104
5105
5106
5107
5108
5109
5110
5111
5112
5113
5114
5115
5116
5117
5118
5119
5120
5121
5122
5123
5124
5125
5126
5127
5128
5129
5130
5131
5132
5133
5134
5135
5136
5137
5138
5139
5140
5141
5142
5143
5144
5145
5146
5147
5148
5149
5150
5151
5152
5153
5154
5155
5156
5157
5158
5159
5160
5161
5162
5163
5164
5165
5166
5167
5168
5169
5170
5171
5172
5173
5174
5175
5176
5177
5178
5179
5180
5181
5182
5183
5184
5185
5186
5187
5188
5189
5190
5191
5192
5193
5194
5195
5196
5197
5198
5199
5200
5201
5202
5203
5204
5205
5206
5207
5208
5209
5210
5211
5212
5213
5214
5215
5216
5217
5218
5219
5220
5221
5222
5223
5224
5225
5226
5227
5228
5229
5230
5231
5232
5233
5234
5235
5236
5237
5238
5239
5240
5241
5242
5243
5244
5245
5246
5247
5248
5249
5250
5251
5252
5253
5254
5255
5256
5257
5258
5259
5260
5261
5262
5263
5264
5265
5266
5267
5268
5269
5270
5271
5272
5273
5274
5275
5276
5277
5278
5279
5280
5281
5282
5283
5284
5285
5286
5287
5288
5289
5290
5291
5292
5293
5294
5295
5296
5297
5298
5299
5300
5301
5302
5303
5304
5305
5306
5307
5308
5309
5310
5311
5312
5313
5314
5315
5316
5317
5318
5319
5320
5321
5322
5323
5324
5325
5326
5327
5328
5329
5330
5331
5332
5333
5334
5335
5336
5337
5338
5339
5340
5341
5342
5343
5344
5345
5346
5347
5348
5349
5350
5351
5352
5353
5354
5355
5356
5357
5358
5359
5360
5361
5362
5363
5364
5365
5366
5367
5368
5369
5370
5371
5372
5373
5374
5375
5376
5377
5378
5379
5380
5381
5382
5383
5384
5385
5386
5387
5388
5389
5390
5391
5392
5393
5394
5395
5396
5397
5398
5399
5400
5401
5402
5403
5404
5405
5406
5407
5408
5409
5410
5411
5412
5413
5414
5415
5416
5417
5418
5419
5420
5421
5422
5423
5424
5425
5426
5427
5428
5429
5430
5431
5432
5433
5434
5435
5436
5437
5438
5439
5440
5441
5442
5443
5444
5445
5446
5447
5448
5449
5450
5451
5452
5453
5454
5455
5456
5457
5458
5459
5460
5461
5462
5463
5464
5465
5466
5467
5468
5469
5470
5471
5472
5473
5474
5475
5476
5477
5478
5479
5480
5481
5482
5483
5484
5485
5486
5487
5488
5489
5490
5491
5492
5493
5494
5495
5496
5497
5498
5499
5500
5501
5502
5503
5504
5505
5506
5507
5508
5509
5510
5511
5512
5513
5514
5515
5516
5517
5518
5519
5520
5521
5522
5523
5524
5525
5526
5527
5528
5529
5530
5531
5532
5533
5534
5535
5536
5537
5538
5539
5540
5541
5542
5543
5544
5545
5546
5547
5548
5549
5550
5551
5552
5553
5554
5555
5556
5557
5558
5559
5560
5561
5562
5563
5564
5565
5566
5567
5568
5569
5570
5571
5572
5573
5574
5575
5576
5577
5578
5579
5580
5581
5582
5583
5584
5585
5586
5587
5588
5589
5590
5591
5592
5593
5594
5595
5596
5597
5598
5599
5600
5601
5602
5603
5604
5605
5606
5607
5608
5609
5610
5611
<?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-Core.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="core">
<h1>Core</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="#core" id="id406">Core</a><ul>
<li><a class="reference internal" href="#stats-metric" id="id407">stats_metric</a></li>
<li><a class="reference internal" href="#peer-class-info" id="id408">peer_class_info</a></li>
<li><a class="reference internal" href="#session-handle" id="id409">session_handle</a></li>
<li><a class="reference internal" href="#session-proxy" id="id410">session_proxy</a></li>
<li><a class="reference internal" href="#session" id="id411">session</a></li>
<li><a class="reference internal" href="#bt-peer-connection-handle" id="id412">bt_peer_connection_handle</a></li>
<li><a class="reference internal" href="#torrent-status" id="id413">torrent_status</a></li>
<li><a class="reference internal" href="#announce-entry" id="id414">announce_entry</a></li>
<li><a class="reference internal" href="#peer-class-type-filter" id="id415">peer_class_type_filter</a></li>
<li><a class="reference internal" href="#block-info" id="id416">block_info</a></li>
<li><a class="reference internal" href="#partial-piece-info" id="id417">partial_piece_info</a></li>
<li><a class="reference internal" href="#torrent-handle" id="id418">torrent_handle</a></li>
<li><a class="reference internal" href="#cache-status" id="id419">cache_status</a></li>
<li><a class="reference internal" href="#web-seed-entry" id="id420">web_seed_entry</a></li>
<li><a class="reference internal" href="#torrent-info" id="id421">torrent_info</a></li>
<li><a class="reference internal" href="#add-torrent-params" id="id422">add_torrent_params</a></li>
<li><a class="reference internal" href="#peer-info" id="id423">peer_info</a></li>
<li><a class="reference internal" href="#peer-request" id="id424">peer_request</a></li>
<li><a class="reference internal" href="#dht-storage-counters" id="id425">dht_storage_counters</a></li>
<li><a class="reference internal" href="#dht-storage-interface" id="id426">dht_storage_interface</a></li>
<li><a class="reference internal" href="#session-stats-metrics" id="id427">session_stats_metrics()</a></li>
<li><a class="reference internal" href="#find-metric-idx" id="id428">find_metric_idx()</a></li>
<li><a class="reference internal" href="#make-magnet-uri" id="id429">make_magnet_uri()</a></li>
<li><a class="reference internal" href="#parse-magnet-uri" id="id430">parse_magnet_uri()</a></li>
<li><a class="reference internal" href="#to-hex" id="id431">to_hex()</a></li>
<li><a class="reference internal" href="#from-hex" id="id432">from_hex()</a></li>
<li><a class="reference internal" href="#version" id="id433">version()</a></li>
<li><a class="reference internal" href="#generate-fingerprint" id="id434">generate_fingerprint()</a></li>
<li><a class="reference internal" href="#hash-value" id="id435">hash_value()</a></li>
<li><a class="reference internal" href="#id399" id="id436">hash_value()</a></li>
<li><a class="reference internal" href="#is-utp-stream-logging" id="id437">is_utp_stream_logging()</a></li>
<li><a class="reference internal" href="#set-utp-stream-logging" id="id438">set_utp_stream_logging()</a></li>
<li><a class="reference internal" href="#verify-message" id="id439">verify_message()</a></li>
<li><a class="reference internal" href="#dht-default-storage-constructor" id="id440">dht_default_storage_constructor()</a></li>
<li><a class="reference internal" href="#sign-mutable-item" id="id441">sign_mutable_item()</a></li>
</ul>
</li>
</ul>
</div>
<a name="stats_metric"></a><div class="section" id="stats-metric">
<h2>stats_metric</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/session_stats.hpp">libtorrent/session_stats.hpp</a>&quot;</p>
<p>describes one statistics metric from the <a class="reference external" href="reference-Core.html#session">session</a>. For more information,
see the <a class="reference external" href="manual-ref.html#session-statistics">session statistics</a> section.</p>
<pre class="literal-block">
struct stats_metric
{
   enum metric_type_t
   {
      type_counter,
      type_gauge,
   };

   char const* name;
   int value_index;
   metric_type_t type;
};
</pre>
<a name="metric_type_t"></a><div class="section" id="enum-metric-type-t">
<h3>enum metric_type_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/session_stats.hpp">libtorrent/session_stats.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="41%" />
<col width="21%" />
<col width="38%" />
</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>type_counter</td>
<td>0</td>
<td>&nbsp;</td>
</tr>
<tr><td>type_gauge</td>
<td>1</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<a name="peer_class_info"></a></div>
</div>
<div class="section" id="peer-class-info">
<h2>peer_class_info</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/peer_class.hpp">libtorrent/peer_class.hpp</a>&quot;</p>
<p>holds settings for a peer class. Used in <a class="reference external" href="reference-Core.html#set_peer_class()">set_peer_class()</a> and
<a class="reference external" href="reference-Core.html#get_peer_class()">get_peer_class()</a> calls.</p>
<pre class="literal-block">
struct peer_class_info
{
   bool ignore_unchoke_slots;
   int connection_limit_factor;
   std::string label;
   int upload_limit;
   int download_limit;
   int upload_priority;
   int download_priority;
};
</pre>
<a name="ignore_unchoke_slots"></a><dl class="docutils">
<dt>ignore_unchoke_slots</dt>
<dd><tt class="docutils literal">ignore_unchoke_slots</tt> determines whether peers should always
unchoke a peer, regardless of the choking algorithm, or if it should
honor the unchoke slot limits. It's used for local peers by default.
If <em>any</em> of the peer classes a peer belongs to has this set to true,
that peer will be unchoked at all times.</dd>
</dl>
<a name="connection_limit_factor"></a><dl class="docutils">
<dt>connection_limit_factor</dt>
<dd>adjusts the connection limit (global and per torrent) that applies to
this peer class. By default, local peers are allowed to exceed the
normal connection limit for instance. This is specified as a percent
factor. 100 makes the peer class apply normally to the limit. 200
means as long as there are fewer connections than twice the limit, we
accept this peer. This factor applies both to the global connection
limit and the per-torrent limit. Note that if not used carefully one
peer class can potentially completely starve out all other over time.</dd>
</dl>
<a name="label"></a><dl class="docutils">
<dt>label</dt>
<dd>not used by libtorrent. It's intended as a potentially user-facing
identifier of this peer class.</dd>
</dl>
<a name="upload_limit"></a>
<a name="download_limit"></a><dl class="docutils">
<dt>upload_limit  download_limit</dt>
<dd>transfer rates limits for the whole peer class. They are specified in
bytes per second and apply to the sum of all peers that are members of
this class.</dd>
</dl>
<a name="upload_priority"></a>
<a name="download_priority"></a><dl class="docutils">
<dt>upload_priority  download_priority</dt>
<dd>relative priorities used by the bandwidth allocator in the rate
limiter. If no rate limits are in use, the priority is not used
either. Priorities start at 1 (0 is not a valid priority) and may not
exceed 255.</dd>
</dl>
<a name="session_handle"></a></div>
<div class="section" id="session-handle">
<h2>session_handle</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/session_handle.hpp">libtorrent/session_handle.hpp</a>&quot;</p>
<pre class="literal-block">
struct session_handle
{
   <strong>session_handle</strong> ();
   <strong>session_handle</strong> (aux::session_impl* impl);
   bool <strong>is_valid</strong> () const;
   void <strong>load_state</strong> (bdecode_node const&amp; e, boost::uint32_t flags = 0xffffffff);
   void <strong>save_state</strong> (entry&amp; e, boost::uint32_t flags = 0xffffffff) const;
   void <strong>refresh_torrent_status</strong> (std::vector&lt;torrent_status&gt;* ret
      , boost::uint32_t flags = 0) const;
   void <strong>get_torrent_status</strong> (std::vector&lt;torrent_status&gt;* ret
      , boost::function&lt;bool(torrent_status const&amp;)&gt; const&amp; pred
      , boost::uint32_t flags = 0) const;
   void <strong>post_torrent_updates</strong> (boost::uint32_t flags = 0xffffffff);
   void <strong>post_session_stats</strong> ();
   void <strong>post_dht_stats</strong> ();
   torrent_handle <strong>find_torrent</strong> (sha1_hash const&amp; info_hash) const;
   std::vector&lt;torrent_handle&gt; <strong>get_torrents</strong> () const;
   void <strong>async_add_torrent</strong> (add_torrent_params const&amp; params);
   torrent_handle <strong>add_torrent</strong> (add_torrent_params const&amp; params, error_code&amp; ec);
   torrent_handle <strong>add_torrent</strong> (add_torrent_params const&amp; params);
   void <strong>resume</strong> ();
   void <strong>pause</strong> ();
   bool <strong>is_paused</strong> () const;
   void <strong>set_load_function</strong> (user_load_function_t fun);
   void <strong>get_cache_info</strong> (cache_status* ret, torrent_handle h = torrent_handle(), int flags = 0) const;
   bool <strong>is_dht_running</strong> () const;
   dht_settings <strong>get_dht_settings</strong> () const;
   void <strong>set_dht_settings</strong> (dht_settings const&amp; settings);
   void <strong>set_dht_storage</strong> (dht::dht_storage_constructor_type sc);
   void <strong>add_dht_node</strong> (std::pair&lt;std::string, int&gt; const&amp; node);
   void <strong>dht_get_item</strong> (sha1_hash const&amp; target);
   void <strong>dht_get_item</strong> (boost::array&lt;char, 32&gt; key
      , std::string salt = std::string());
   sha1_hash <strong>dht_put_item</strong> (entry data);
   void <strong>dht_put_item</strong> (boost::array&lt;char, 32&gt; key
      , boost::function&lt;void(entry&amp;, boost::array&lt;char,64&gt;&amp;
      , boost::uint64_t&amp;, std::string const&amp;)&gt; cb
      , std::string salt = std::string());
   void <strong>dht_get_peers</strong> (sha1_hash const&amp; info_hash);
   void <strong>dht_announce</strong> (sha1_hash const&amp; info_hash, int port = 0, int flags = 0);
   void <strong>dht_direct_request</strong> (udp::endpoint ep, entry const&amp; e, void* userdata = 0);
   void <strong>add_extension</strong> (boost::function&lt;boost::shared_ptr&lt;torrent_plugin&gt;(
      torrent_handle const&amp;, void*)&gt; ext);
   void <strong>add_extension</strong> (boost::shared_ptr&lt;plugin&gt; ext);
   ip_filter <strong>get_ip_filter</strong> () const;
   void <strong>set_ip_filter</strong> (ip_filter const&amp; f);
   void <strong>set_port_filter</strong> (port_filter const&amp; f);
   void <strong>set_key</strong> (int key);
   bool <strong>is_listening</strong> () const;
   unsigned short <strong>listen_port</strong> () const;
   unsigned short <strong>ssl_listen_port</strong> () const;
   ip_filter <strong>get_peer_class_filter</strong> () const;
   void <strong>set_peer_class_filter</strong> (ip_filter const&amp; f);
   void <strong>set_peer_class_type_filter</strong> (peer_class_type_filter const&amp; f);
   peer_class_type_filter <strong>get_peer_class_type_filter</strong> () const;
   peer_class_t <strong>create_peer_class</strong> (char const* name);
   void <strong>delete_peer_class</strong> (peer_class_t cid);
   peer_class_info <strong>get_peer_class</strong> (peer_class_t cid);
   void <strong>set_peer_class</strong> (peer_class_t cid, peer_class_info const&amp; pci);
   void <strong>remove_torrent</strong> (const torrent_handle&amp; h, int options = 0);
   settings_pack <strong>get_settings</strong> () const;
   void <strong>apply_settings</strong> (settings_pack const&amp; s);
   void <strong>pop_alerts</strong> (std::vector&lt;alert*&gt;* alerts);
   void <strong>set_alert_notify</strong> (boost::function&lt;void()&gt; const&amp; fun);
   alert* <strong>wait_for_alert</strong> (time_duration max_wait);
   void <strong>delete_port_mapping</strong> (int handle);
   int <strong>add_port_mapping</strong> (protocol_type t, int external_port, int local_port);
   aux::session_impl* <strong>native_handle</strong> () const;

   enum save_state_flags_t
   {
      save_settings,
      save_dht_settings,
      save_dht_state,
   };

   enum options_t
   {
      delete_files,
      delete_partfile,
   };

   enum session_flags_t
   {
      add_default_plugins,
      start_default_features,
   };

   enum protocol_type
   {
      udp,
      tcp,
   };
};
</pre>
<a name="load_state()"></a>
<a name="save_state()"></a><div class="section" id="load-state-save-state">
<h3>load_state() save_state()</h3>
<pre class="literal-block">
void <strong>load_state</strong> (bdecode_node const&amp; e, boost::uint32_t flags = 0xffffffff);
void <strong>save_state</strong> (entry&amp; e, boost::uint32_t flags = 0xffffffff) const;
</pre>
<p>loads and saves all <a class="reference external" href="reference-Core.html#session">session</a> settings, including <a class="reference external" href="reference-Settings.html#dht_settings">dht_settings</a>,
encryption settings and proxy settings. <tt class="docutils literal">save_state</tt> writes all keys
to the <tt class="docutils literal">entry</tt> that's passed in, which needs to either not be
initialized, or initialized as a dictionary.</p>
<p><tt class="docutils literal">load_state</tt> expects a <a class="reference external" href="reference-Bdecoding.html#bdecode_node">bdecode_node</a> which can be built from a bencoded
buffer with <a class="reference external" href="reference-Bencoding.html#bdecode()">bdecode()</a>.</p>
<p>The <tt class="docutils literal">flags</tt> argument is used to filter which parts of the <a class="reference external" href="reference-Core.html#session">session</a>
state to save or load. By default, all state is saved/restored (except
for the individual torrents). see <a class="reference external" href="reference-Core.html#save_state_flags_t">save_state_flags_t</a></p>
<p>When saving settings, there are two fields that are <em>not</em> loaded.
<tt class="docutils literal">peer_fingerprint</tt> and <tt class="docutils literal">user_agent</tt>. Those are left as configured
by the <tt class="docutils literal">session_settings</tt> passed to the <a class="reference external" href="reference-Core.html#session">session</a> constructor or
subsequently set via <a class="reference external" href="reference-Core.html#apply_settings()">apply_settings()</a>.</p>
<a name="get_torrent_status()"></a>
<a name="refresh_torrent_status()"></a></div>
<div class="section" id="get-torrent-status-refresh-torrent-status">
<h3>get_torrent_status() refresh_torrent_status()</h3>
<pre class="literal-block">
void <strong>refresh_torrent_status</strong> (std::vector&lt;torrent_status&gt;* ret
      , boost::uint32_t flags = 0) const;
void <strong>get_torrent_status</strong> (std::vector&lt;torrent_status&gt;* ret
      , boost::function&lt;bool(torrent_status const&amp;)&gt; const&amp; pred
      , boost::uint32_t flags = 0) const;
</pre>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">these calls are potentially expensive and won't scale well with
lots of torrents. If you're concerned about performance, consider
using <tt class="docutils literal">post_torrent_updates()</tt> instead.</p>
</div>
<p><tt class="docutils literal">get_torrent_status</tt> returns a vector of the <a class="reference external" href="reference-Core.html#torrent_status">torrent_status</a> for
every torrent which satisfies <tt class="docutils literal">pred</tt>, which is a predicate function
which determines if a torrent should be included in the returned set
or not. Returning true means it should be included and false means
excluded. The <tt class="docutils literal">flags</tt> argument is the same as to
<tt class="docutils literal"><span class="pre">torrent_handle::status()</span></tt>. Since <tt class="docutils literal">pred</tt> is guaranteed to be
called for every torrent, it may be used to count the number of
torrents of different categories as well.</p>
<p><tt class="docutils literal">refresh_torrent_status</tt> takes a vector of <a class="reference external" href="reference-Core.html#torrent_status">torrent_status</a> structs
(for instance the same vector that was returned by
<a class="reference external" href="reference-Core.html#get_torrent_status()">get_torrent_status()</a> ) and refreshes the status based on the
<tt class="docutils literal">handle</tt> member. It is possible to use this function by first
setting up a vector of default constructed <tt class="docutils literal">torrent_status</tt> objects,
only initializing the <tt class="docutils literal">handle</tt> member, in order to request the
torrent status for multiple torrents in a single call. This can save a
significant amount of time if you have a lot of torrents.</p>
<p>Any <a class="reference external" href="reference-Core.html#torrent_status">torrent_status</a> object whose <tt class="docutils literal">handle</tt> member is not referring to
a valid torrent are ignored.</p>
<p>The intended use of these functions is to start off by calling
<tt class="docutils literal">get_torrent_status()</tt> to get a list of all torrents that match your
criteria. Then call <tt class="docutils literal">refresh_torrent_status()</tt> on that list. This
will only refresh the status for the torrents in your list, and thus
ignore all other torrents you might be running. This may save a
significant amount of time, especially if the number of torrents you're
interested in is small. In order to keep your list of interested
torrents up to date, you can either call <tt class="docutils literal">get_torrent_status()</tt> from
time to time, to include torrents you might have become interested in
since the last time. In order to stop refreshing a certain torrent,
simply remove it from the list.</p>
<a name="post_torrent_updates()"></a></div>
<div class="section" id="post-torrent-updates">
<h3>post_torrent_updates()</h3>
<pre class="literal-block">
void <strong>post_torrent_updates</strong> (boost::uint32_t flags = 0xffffffff);
</pre>
<p>This functions instructs the <a class="reference external" href="reference-Core.html#session">session</a> to post the <a class="reference external" href="reference-Alerts.html#state_update_alert">state_update_alert</a>,
containing the status of all torrents whose state changed since the
last time this function was called.</p>
<p>Only torrents who has the state subscription flag set will be
included. This flag is on by default. See <a class="reference external" href="reference-Core.html#add_torrent_params">add_torrent_params</a>.
the <tt class="docutils literal">flags</tt> argument is the same as for <a class="reference external" href="reference-Core.html#status()">torrent_handle::status()</a>.
see <a class="reference external" href="reference-Core.html#status_flags_t">torrent_handle::status_flags_t</a>.</p>
<a name="post_session_stats()"></a></div>
<div class="section" id="post-session-stats">
<h3>post_session_stats()</h3>
<pre class="literal-block">
void <strong>post_session_stats</strong> ();
</pre>
<p>This function will post a <a class="reference external" href="reference-Alerts.html#session_stats_alert">session_stats_alert</a> object, containing a
snapshot of the performance counters from the internals of libtorrent.
To interpret these counters, query the <a class="reference external" href="reference-Core.html#session">session</a> via
<a class="reference external" href="reference-Core.html#session_stats_metrics()">session_stats_metrics()</a>.</p>
<p>For more information, see the <a class="reference external" href="manual-ref.html#session-statistics">session statistics</a> section.</p>
<a name="post_dht_stats()"></a></div>
<div class="section" id="post-dht-stats">
<h3>post_dht_stats()</h3>
<pre class="literal-block">
void <strong>post_dht_stats</strong> ();
</pre>
<p>This will cause a <a class="reference external" href="reference-Alerts.html#dht_stats_alert">dht_stats_alert</a> to be posted.</p>
<a name="find_torrent()"></a>
<a name="get_torrents()"></a></div>
<div class="section" id="find-torrent-get-torrents">
<h3>find_torrent() get_torrents()</h3>
<pre class="literal-block">
torrent_handle <strong>find_torrent</strong> (sha1_hash const&amp; info_hash) const;
std::vector&lt;torrent_handle&gt; <strong>get_torrents</strong> () const;
</pre>
<p><tt class="docutils literal">find_torrent()</tt> looks for a torrent with the given info-hash. In
case there is such a torrent in the <a class="reference external" href="reference-Core.html#session">session</a>, a <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> to that
torrent is returned. In case the torrent cannot be found, an invalid
<a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> is returned.</p>
<p>See <tt class="docutils literal"><span class="pre">torrent_handle::is_valid()</span></tt> to know if the torrent was found or
not.</p>
<p><tt class="docutils literal">get_torrents()</tt> returns a vector of torrent_handles to all the
torrents currently in the <a class="reference external" href="reference-Core.html#session">session</a>.</p>
<a name="add_torrent()"></a>
<a name="async_add_torrent()"></a></div>
<div class="section" id="add-torrent-async-add-torrent">
<h3>add_torrent() async_add_torrent()</h3>
<pre class="literal-block">
void <strong>async_add_torrent</strong> (add_torrent_params const&amp; params);
torrent_handle <strong>add_torrent</strong> (add_torrent_params const&amp; params, error_code&amp; ec);
torrent_handle <strong>add_torrent</strong> (add_torrent_params const&amp; params);
</pre>
<p>You add torrents through the <a class="reference external" href="reference-Core.html#add_torrent()">add_torrent()</a> function where you give an
object with all the parameters. The <a class="reference external" href="reference-Core.html#add_torrent()">add_torrent()</a> overloads will block
until the torrent has been added (or failed to be added) and returns
an error code and a <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a>. In order to add torrents more
efficiently, consider using <a class="reference external" href="reference-Core.html#async_add_torrent()">async_add_torrent()</a> which returns
immediately, without waiting for the torrent to add. Notification of
the torrent being added is sent as <a class="reference external" href="reference-Alerts.html#add_torrent_alert">add_torrent_alert</a>.</p>
<p>The overload that does not take an error_code throws an exception on
error and is not available when building without exception support.
The <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> returned by <a class="reference external" href="reference-Core.html#add_torrent()">add_torrent()</a> can be used to retrieve
information about the torrent's progress, its peers etc. It is also
used to abort a torrent.</p>
<p>If the torrent you are trying to add already exists in the <a class="reference external" href="reference-Core.html#session">session</a> (is
either queued for checking, being checked or downloading)
<tt class="docutils literal">add_torrent()</tt> will throw <a class="reference external" href="reference-Error_Codes.html#libtorrent_exception">libtorrent_exception</a> which derives from
<tt class="docutils literal"><span class="pre">std::exception</span></tt> unless duplicate_is_error is set to false. In that
case, <a class="reference external" href="reference-Core.html#add_torrent()">add_torrent()</a> will return the handle to the existing torrent.</p>
<p>all torrent_handles must be destructed before the <a class="reference external" href="reference-Core.html#session">session</a> is destructed!</p>
<a name="pause()"></a>
<a name="resume()"></a>
<a name="is_paused()"></a></div>
<div class="section" id="pause-resume-is-paused">
<h3>pause() resume() is_paused()</h3>
<pre class="literal-block">
void <strong>resume</strong> ();
void <strong>pause</strong> ();
bool <strong>is_paused</strong> () const;
</pre>
<p>Pausing the <a class="reference external" href="reference-Core.html#session">session</a> has the same effect as pausing every torrent in
it, except that torrents will not be resumed by the auto-manage
mechanism. Resuming will restore the torrents to their previous paused
state. i.e. the <a class="reference external" href="reference-Core.html#session">session</a> pause state is separate from the torrent pause
state. A torrent is inactive if it is paused or if the <a class="reference external" href="reference-Core.html#session">session</a> is
paused.</p>
<a name="set_load_function()"></a></div>
<div class="section" id="set-load-function">
<h3>set_load_function()</h3>
<pre class="literal-block">
void <strong>set_load_function</strong> (user_load_function_t fun);
</pre>
<p><em>the feature of dynamically loading/unloading torrents is deprecated
and discouraged</em></p>
<p>This function enables <a class="reference external" href="manual-ref.html#dynamic-loading-of-torrent-files">dynamic loading of torrent files</a>. When a
torrent is unloaded but needs to be available in memory, this function
is called <strong>from within the libtorrent network thread</strong>. From within
this thread, you can <strong>not</strong> use any of the public APIs of libtorrent
itself. The the info-hash of the torrent is passed in to the function
and it is expected to fill in the passed in <tt class="docutils literal">vector&lt;char&gt;</tt> with the
.torrent file corresponding to it.</p>
<p>If there is an error loading the torrent file, the <tt class="docutils literal">error_code</tt>
(<tt class="docutils literal">ec</tt>) should be set to reflect the error. In such case, the torrent
itself is stopped and set to an error state with the corresponding
error code.</p>
<p>Given that the function is called from the internal network thread of
libtorrent, it's important to not stall. libtorrent will not be able
to send nor receive any data until the function call returns.</p>
<p>The signature of the function to pass in is:</p>
<pre class="literal-block">
void fun(sha1_hash const&amp; info_hash, std::vector&lt;char&gt;&amp; buf, error_code&amp; ec);
</pre>
<a name="get_cache_info()"></a></div>
<div class="section" id="get-cache-info">
<h3>get_cache_info()</h3>
<pre class="literal-block">
void <strong>get_cache_info</strong> (cache_status* ret, torrent_handle h = torrent_handle(), int flags = 0) const;
</pre>
<p>Fills in the <a class="reference external" href="reference-Core.html#cache_status">cache_status</a> struct with information about the given torrent.
If <tt class="docutils literal">flags</tt> is <tt class="docutils literal"><span class="pre">session::disk_cache_no_pieces</span></tt> the <tt class="docutils literal"><span class="pre">cache_status::pieces</span></tt> field
will not be set. This may significantly reduce the cost of this call.</p>
<a name="get_dht_settings()"></a>
<a name="is_dht_running()"></a>
<a name="set_dht_settings()"></a></div>
<div class="section" id="get-dht-settings-is-dht-running-set-dht-settings">
<h3>get_dht_settings() is_dht_running() set_dht_settings()</h3>
<pre class="literal-block">
bool <strong>is_dht_running</strong> () const;
dht_settings <strong>get_dht_settings</strong> () const;
void <strong>set_dht_settings</strong> (dht_settings const&amp; settings);
</pre>
<p><tt class="docutils literal">set_dht_settings</tt> sets some parameters available to the dht node.
See <a class="reference external" href="reference-Settings.html#dht_settings">dht_settings</a> for more information.</p>
<p><tt class="docutils literal">is_dht_running()</tt> returns true if the DHT support has been started
and false
otherwise.</p>
<p><tt class="docutils literal">get_dht_settings()</tt> returns the current settings</p>
<a name="set_dht_storage()"></a></div>
<div class="section" id="set-dht-storage">
<h3>set_dht_storage()</h3>
<pre class="literal-block">
void <strong>set_dht_storage</strong> (dht::dht_storage_constructor_type sc);
</pre>
<p><tt class="docutils literal">set_dht_storage</tt> set a dht custom storage constructor function
to be used internally when the dht is created.</p>
<p>Since the dht storage is a critical component for the dht behavior,
this function will only be effective the next time the dht is started.
If you never touch this feature, a default map-memory based storage
is used.</p>
<p>If you want to make sure the dht is initially created with your
custom storage, create a <a class="reference external" href="reference-Core.html#session">session</a> with the setting
<tt class="docutils literal"><span class="pre">settings_pack::enable_dht</span></tt> to false, set your constructor function
and call <tt class="docutils literal">apply_settings</tt> with <tt class="docutils literal"><span class="pre">settings_pack::enable_dht</span></tt> to true.</p>
<a name="add_dht_node()"></a></div>
<div class="section" id="add-dht-node">
<h3>add_dht_node()</h3>
<pre class="literal-block">
void <strong>add_dht_node</strong> (std::pair&lt;std::string, int&gt; const&amp; node);
</pre>
<p><tt class="docutils literal">add_dht_node</tt> takes a host name and port pair. That endpoint will be
pinged, and if a valid DHT reply is received, the node will be added to
the routing table.</p>
<a name="dht_get_item()"></a></div>
<div class="section" id="dht-get-item">
<h3>dht_get_item()</h3>
<pre class="literal-block">
void <strong>dht_get_item</strong> (sha1_hash const&amp; target);
</pre>
<p>query the DHT for an immutable item at the <tt class="docutils literal">target</tt> hash.
the result is posted as a <a class="reference external" href="reference-Alerts.html#dht_immutable_item_alert">dht_immutable_item_alert</a>.</p>
<a name="dht_get_item()"></a></div>
<div class="section" id="id55">
<h3>dht_get_item()</h3>
<pre class="literal-block">
void <strong>dht_get_item</strong> (boost::array&lt;char, 32&gt; key
      , std::string salt = std::string());
</pre>
<p>query the DHT for a mutable item under the public key <tt class="docutils literal">key</tt>.
this is an ed25519 key. <tt class="docutils literal">salt</tt> is optional and may be left
as an empty string if no salt is to be used.
if the item is found in the DHT, a <a class="reference external" href="reference-Alerts.html#dht_mutable_item_alert">dht_mutable_item_alert</a> is
posted.</p>
<a name="dht_put_item()"></a></div>
<div class="section" id="dht-put-item">
<h3>dht_put_item()</h3>
<pre class="literal-block">
sha1_hash <strong>dht_put_item</strong> (entry data);
</pre>
<p>store the given bencoded data as an immutable item in the DHT.
the returned hash is the key that is to be used to look the item
up again. It's just the SHA-1 hash of the bencoded form of the
structure.</p>
<a name="dht_put_item()"></a></div>
<div class="section" id="id57">
<h3>dht_put_item()</h3>
<pre class="literal-block">
void <strong>dht_put_item</strong> (boost::array&lt;char, 32&gt; key
      , boost::function&lt;void(entry&amp;, boost::array&lt;char,64&gt;&amp;
      , boost::uint64_t&amp;, std::string const&amp;)&gt; cb
      , std::string salt = std::string());
</pre>
<p>store a mutable item. The <tt class="docutils literal">key</tt> is the public key the blob is
to be stored under. The optional <tt class="docutils literal">salt</tt> argument is a string that
is to be mixed in with the key when determining where in the DHT
the value is to be stored. The callback function is called from within
the libtorrent network thread once we've found where to store the blob,
possibly with the current value stored under the key.
The values passed to the callback functions are:</p>
<dl class="docutils">
<dt>entry&amp; value</dt>
<dd>the current value stored under the key (may be empty). Also expected
to be set to the value to be stored by the function.</dd>
<dt>boost::array&lt;char,64&gt;&amp; signature</dt>
<dd>the signature authenticating the current value. This may be zeros
if there is currently no value stored. The function is expected to
fill in this buffer with the signature of the new value to store.
To generate the signature, you may want to use the
<tt class="docutils literal">sign_mutable_item</tt> function.</dd>
<dt>boost::uint64_t&amp; seq</dt>
<dd>current sequence number. May be zero if there is no current value.
The function is expected to set this to the new sequence number of
the value that is to be stored. Sequence numbers must be monotonically
increasing. Attempting to overwrite a value with a lower or equal
sequence number will fail, even if the signature is correct.</dd>
<dt>std::string const&amp; salt</dt>
<dd>this is the salt that was used for this put call.</dd>
</dl>
<p>Since the callback function <tt class="docutils literal">cb</tt> is called from within libtorrent,
it is critical to not perform any blocking operations. Ideally not
even locking a mutex. Pass any data required for this function along
with the function object's context and make the function entirely
self-contained. The only reason data blob's value is computed
via a function instead of just passing in the new value is to avoid
race conditions. If you want to <em>update</em> the value in the DHT, you
must first retrieve it, then modify it, then write it back. The way
the DHT works, it is natural to always do a lookup before storing and
calling the callback in between is convenient.</p>
<a name="dht_direct_request()"></a></div>
<div class="section" id="dht-direct-request">
<h3>dht_direct_request()</h3>
<pre class="literal-block">
void <strong>dht_direct_request</strong> (udp::endpoint ep, entry const&amp; e, void* userdata = 0);
</pre>
<p>Send an arbitrary DHT request directly to the specified endpoint. This
function is intended for use by plugins. When a response is received
or the request times out, a <a class="reference external" href="reference-Alerts.html#dht_direct_response_alert">dht_direct_response_alert</a> will be posted
with the response (if any) and the userdata pointer passed in here.
Since this <a class="reference external" href="reference-Alerts.html#alert">alert</a> is a response to an explicit call, it will always be
posted, regardless of the <a class="reference external" href="reference-Alerts.html#alert">alert</a> mask.</p>
<a name="add_extension()"></a></div>
<div class="section" id="add-extension">
<h3>add_extension()</h3>
<pre class="literal-block">
void <strong>add_extension</strong> (boost::function&lt;boost::shared_ptr&lt;torrent_plugin&gt;(
      torrent_handle const&amp;, void*)&gt; ext);
void <strong>add_extension</strong> (boost::shared_ptr&lt;plugin&gt; ext);
</pre>
<p>This function adds an extension to this <a class="reference external" href="reference-Core.html#session">session</a>. The argument is a
function object that is called with a <tt class="docutils literal">torrent_handle</tt> and which should
return a <tt class="docutils literal"><span class="pre">boost::shared_ptr&lt;torrent_plugin&gt;</span></tt>. To write custom
plugins, see <a class="reference external" href="libtorrent_plugins.html">libtorrent plugins</a>. For the typical bittorrent client
all of these extensions should be added. The main plugins implemented
in libtorrent are:</p>
<dl class="docutils">
<dt>metadata extension</dt>
<dd>Allows peers to download the metadata (.torrent files) from the swarm
directly. Makes it possible to join a swarm with just a tracker and
info-hash.</dd>
</dl>
<pre class="code c++ literal-block">
<span class="comment preproc">#include</span> <span class="comment preprocfile">&lt;libtorrent/extensions/metadata_transfer.hpp&gt;</span><span class="comment preproc">
</span><span class="name">ses</span><span class="punctuation">.</span><span class="name">add_extension</span><span class="punctuation">(</span><span class="operator">&amp;</span><span class="name">libtorrent</span><span class="operator">::</span><span class="name">create_metadata_plugin</span><span class="punctuation">);</span>
</pre>
<dl class="docutils">
<dt>uTorrent metadata</dt>
<dd>Same as <tt class="docutils literal">metadata extension</tt> but compatible with uTorrent.</dd>
</dl>
<pre class="code c++ literal-block">
<span class="comment preproc">#include</span> <span class="comment preprocfile">&lt;libtorrent/extensions/ut_metadata.hpp&gt;</span><span class="comment preproc">
</span><span class="name">ses</span><span class="punctuation">.</span><span class="name">add_extension</span><span class="punctuation">(</span><span class="operator">&amp;</span><span class="name">libtorrent</span><span class="operator">::</span><span class="name">create_ut_metadata_plugin</span><span class="punctuation">);</span>
</pre>
<dl class="docutils">
<dt>uTorrent peer exchange</dt>
<dd>Exchanges peers between clients.</dd>
</dl>
<pre class="code c++ literal-block">
<span class="comment preproc">#include</span> <span class="comment preprocfile">&lt;libtorrent/extensions/ut_pex.hpp&gt;</span><span class="comment preproc">
</span><span class="name">ses</span><span class="punctuation">.</span><span class="name">add_extension</span><span class="punctuation">(</span><span class="operator">&amp;</span><span class="name">libtorrent</span><span class="operator">::</span><span class="name">create_ut_pex_plugin</span><span class="punctuation">);</span>
</pre>
<dl class="docutils">
<dt>smart ban <a class="reference external" href="reference-Plugins.html#plugin">plugin</a></dt>
<dd>A <a class="reference external" href="reference-Plugins.html#plugin">plugin</a> that, with a small overhead, can ban peers
that sends bad data with very high accuracy. Should
eliminate most problems on poisoned torrents.</dd>
</dl>
<pre class="code c++ literal-block">
<span class="comment preproc">#include</span> <span class="comment preprocfile">&lt;libtorrent/extensions/smart_ban.hpp&gt;</span><span class="comment preproc">
</span><span class="name">ses</span><span class="punctuation">.</span><span class="name">add_extension</span><span class="punctuation">(</span><span class="operator">&amp;</span><span class="name">libtorrent</span><span class="operator">::</span><span class="name">create_smart_ban_plugin</span><span class="punctuation">);</span>
</pre>
<a name="get_ip_filter()"></a>
<a name="set_ip_filter()"></a></div>
<div class="section" id="get-ip-filter-set-ip-filter">
<h3>get_ip_filter() set_ip_filter()</h3>
<pre class="literal-block">
ip_filter <strong>get_ip_filter</strong> () const;
void <strong>set_ip_filter</strong> (ip_filter const&amp; f);
</pre>
<p>Sets a filter that will be used to reject and accept incoming as well
as outgoing connections based on their originating ip address. The
default filter will allow connections to any ip address. To build a
set of rules for which addresses are accepted and not, see <a class="reference external" href="reference-Filter.html#ip_filter">ip_filter</a>.</p>
<p>Each time a peer is blocked because of the IP filter, a
<a class="reference external" href="reference-Alerts.html#peer_blocked_alert">peer_blocked_alert</a> is generated. <tt class="docutils literal">get_ip_filter()</tt> Returns the
<a class="reference external" href="reference-Filter.html#ip_filter">ip_filter</a> currently in the <a class="reference external" href="reference-Core.html#session">session</a>. See <a class="reference external" href="reference-Filter.html#ip_filter">ip_filter</a>.</p>
<a name="set_port_filter()"></a></div>
<div class="section" id="set-port-filter">
<h3>set_port_filter()</h3>
<pre class="literal-block">
void <strong>set_port_filter</strong> (port_filter const&amp; f);
</pre>
<p>apply <a class="reference external" href="reference-Filter.html#port_filter">port_filter</a> <tt class="docutils literal">f</tt> to incoming and outgoing peers. a port filter
will reject making outgoing peer connections to certain remote ports.
The main intention is to be able to avoid triggering certain
anti-virus software by connecting to SMTP, FTP ports.</p>
<a name="set_key()"></a></div>
<div class="section" id="set-key">
<h3>set_key()</h3>
<pre class="literal-block">
void <strong>set_key</strong> (int key);
</pre>
<p>sets the key sent to trackers. If it's not set, it is initialized
by libtorrent. The key may be used by the tracker to identify the
peer potentially across you changing your IP.</p>
<a name="listen_port()"></a>
<a name="ssl_listen_port()"></a>
<a name="is_listening()"></a></div>
<div class="section" id="listen-port-ssl-listen-port-is-listening">
<h3>listen_port() ssl_listen_port() is_listening()</h3>
<pre class="literal-block">
bool <strong>is_listening</strong> () const;
unsigned short <strong>listen_port</strong> () const;
unsigned short <strong>ssl_listen_port</strong> () const;
</pre>
<p><tt class="docutils literal">is_listening()</tt> will tell you whether or not the <a class="reference external" href="reference-Core.html#session">session</a> has
successfully opened a listening port. If it hasn't, this function will
return false, and then you can set a new
<a class="reference external" href="reference-Settings.html#listen_interfaces">settings_pack::listen_interfaces</a> to try another interface and port to
bind to.</p>
<p><tt class="docutils literal">listen_port()</tt> returns the port we ended up listening on.</p>
<a name="get_peer_class_filter()"></a>
<a name="set_peer_class_filter()"></a></div>
<div class="section" id="get-peer-class-filter-set-peer-class-filter">
<h3>get_peer_class_filter() set_peer_class_filter()</h3>
<pre class="literal-block">
ip_filter <strong>get_peer_class_filter</strong> () const;
void <strong>set_peer_class_filter</strong> (ip_filter const&amp; f);
</pre>
<p>Sets the peer class filter for this <a class="reference external" href="reference-Core.html#session">session</a>. All new peer connections
will take this into account and be added to the peer classes specified
by this filter, based on the peer's IP address.</p>
<p>The ip-filter essentially maps an IP -&gt; uint32. Each bit in that 32
bit integer represents a peer class. The least significant bit
represents class 0, the next bit class 1 and so on.</p>
<p>For more info, see <a class="reference external" href="reference-Filter.html#ip_filter">ip_filter</a>.</p>
<p>For example, to make all peers in the range 200.1.1.0 - 200.1.255.255
belong to their own peer class, apply the following filter:</p>
<pre class="code c++ literal-block">
<span class="name">ip_filter</span> <span class="name">f</span> <span class="operator">=</span> <span class="name">ses</span><span class="punctuation">.</span><span class="name">get_peer_class_filter</span><span class="punctuation">();</span>
<span class="name">peer_class_t</span> <span class="keyword">const</span> <span class="name">my_class</span> <span class="operator">=</span> <span class="name">ses</span><span class="punctuation">.</span><span class="name">create_peer_class</span><span class="punctuation">(</span><span class="literal string">&quot;200.1.x.x IP range&quot;</span><span class="punctuation">);</span>
<span class="name">f</span><span class="punctuation">.</span><span class="name">add_rule</span><span class="punctuation">(</span><span class="name">make_address</span><span class="punctuation">(</span><span class="literal string">&quot;200.1.1.0&quot;</span><span class="punctuation">),</span> <span class="name">make_address</span><span class="punctuation">(</span><span class="literal string">&quot;200.1.255.255&quot;</span><span class="punctuation">)</span>
        <span class="punctuation">,</span> <span class="literal number integer">1</span> <span class="operator">&lt;&lt;</span> <span class="name">my_class</span><span class="punctuation">);</span>
<span class="name">ses</span><span class="punctuation">.</span><span class="name">set_peer_class_filter</span><span class="punctuation">(</span><span class="name">f</span><span class="punctuation">);</span>
</pre>
<p>This setting only applies to new connections, it won't affect existing
peer connections.</p>
<p>This function is limited to only peer class 0-31, since there are only
32 bits in the IP range mapping. Only the set bits matter; no peer
class will be removed from a peer as a result of this call, peer
classes are only added.</p>
<p>The <tt class="docutils literal">peer_class</tt> argument cannot be greater than 31. The bitmasks
representing peer classes in the <tt class="docutils literal">peer_class_filter</tt> are 32 bits.</p>
<p>The <tt class="docutils literal">get_peer_class_filter()</tt> function returns the current filter.</p>
<p>For more information, see <a class="reference external" href="manual-ref.html#peer-classes">peer classes</a>.</p>
<a name="set_peer_class_type_filter()"></a>
<a name="get_peer_class_type_filter()"></a></div>
<div class="section" id="set-peer-class-type-filter-get-peer-class-type-filter">
<h3>set_peer_class_type_filter() get_peer_class_type_filter()</h3>
<pre class="literal-block">
void <strong>set_peer_class_type_filter</strong> (peer_class_type_filter const&amp; f);
peer_class_type_filter <strong>get_peer_class_type_filter</strong> () const;
</pre>
<p>Sets and gets the <em>peer class type filter</em>. This is controls automatic
peer class assignments to peers based on what kind of socket it is.</p>
<p>It does not only support assigning peer classes, it also supports
removing peer classes based on socket type.</p>
<p>The order of these rules being applied are:</p>
<ol class="arabic simple">
<li>peer-class IP filter</li>
<li>peer-class type filter, removing classes</li>
<li>peer-class type filter, adding classes</li>
</ol>
<p>For more information, see <a class="reference external" href="manual-ref.html#peer-classes">peer classes</a>.</p>
<a name="create_peer_class()"></a></div>
<div class="section" id="create-peer-class">
<h3>create_peer_class()</h3>
<pre class="literal-block">
peer_class_t <strong>create_peer_class</strong> (char const* name);
</pre>
<p>Creates a new peer class (see <a class="reference external" href="manual-ref.html#peer-classes">peer classes</a>) with the given name. The
returned integer is the new peer class identifier. Peer classes may
have the same name, so each invocation of this function creates a new
class and returns a unique identifier.</p>
<p>Identifiers are assigned from low numbers to higher. So if you plan on
using certain peer classes in a call to <a class="reference external" href="reference-Core.html#set_peer_class_filter()">set_peer_class_filter()</a>,
make sure to create those early on, to get low identifiers.</p>
<p>For more information on peer classes, see <a class="reference external" href="manual-ref.html#peer-classes">peer classes</a>.</p>
<a name="delete_peer_class()"></a></div>
<div class="section" id="delete-peer-class">
<h3>delete_peer_class()</h3>
<pre class="literal-block">
void <strong>delete_peer_class</strong> (peer_class_t cid);
</pre>
<p>This call dereferences the reference count of the specified peer
class. When creating a peer class it's automatically referenced by 1.
If you want to recycle a peer class, you may call this function. You
may only call this function <strong>once</strong> per peer class you create.
Calling it more than once for the same class will lead to memory
corruption.</p>
<p>Since peer classes are reference counted, this function will not
remove the peer class if it's still assigned to torrents or peers. It
will however remove it once the last peer and torrent drops their
references to it.</p>
<p>There is no need to call this function for custom peer classes. All
peer classes will be properly destructed when the <a class="reference external" href="reference-Core.html#session">session</a> object
destructs.</p>
<p>For more information on peer classes, see <a class="reference external" href="manual-ref.html#peer-classes">peer classes</a>.</p>
<a name="get_peer_class()"></a>
<a name="set_peer_class()"></a></div>
<div class="section" id="get-peer-class-set-peer-class">
<h3>get_peer_class() set_peer_class()</h3>
<pre class="literal-block">
peer_class_info <strong>get_peer_class</strong> (peer_class_t cid);
void <strong>set_peer_class</strong> (peer_class_t cid, peer_class_info const&amp; pci);
</pre>
<p>These functions queries information from a peer class and updates the
configuration of a peer class, respectively.</p>
<p><tt class="docutils literal">cid</tt> must refer to an existing peer class. If it does not, the
return value of <tt class="docutils literal">get_peer_class()</tt> is undefined.</p>
<p><tt class="docutils literal">set_peer_class()</tt> sets all the information in the
<a class="reference external" href="reference-Core.html#peer_class_info">peer_class_info</a> object in the specified peer class. There is no
option to only update a single property.</p>
<p>A peer or torrent belonging to more than one class, the highest
priority among any of its classes is the one that is taken into
account.</p>
<p>For more information, see <a class="reference external" href="manual-ref.html#peer-classes">peer classes</a>.</p>
<a name="remove_torrent()"></a></div>
<div class="section" id="remove-torrent">
<h3>remove_torrent()</h3>
<pre class="literal-block">
void <strong>remove_torrent</strong> (const torrent_handle&amp; h, int options = 0);
</pre>
<p><tt class="docutils literal">remove_torrent()</tt> will close all peer connections associated with
the torrent and tell the tracker that we've stopped participating in
the swarm. This operation cannot fail. When it completes, you will
receive a <a class="reference external" href="reference-Alerts.html#torrent_removed_alert">torrent_removed_alert</a>.</p>
<p>The optional second argument <tt class="docutils literal">options</tt> can be used to delete all the
files downloaded by this torrent. To do so, pass in the value
<tt class="docutils literal"><span class="pre">session::delete_files</span></tt>. The removal of the torrent is asynchronous,
there is no guarantee that adding the same torrent immediately after
it was removed will not throw a <a class="reference external" href="reference-Error_Codes.html#libtorrent_exception">libtorrent_exception</a> exception. Once
the torrent is deleted, a <a class="reference external" href="reference-Alerts.html#torrent_deleted_alert">torrent_deleted_alert</a> is posted.</p>
<a name="get_settings()"></a>
<a name="apply_settings()"></a></div>
<div class="section" id="get-settings-apply-settings">
<h3>get_settings() apply_settings()</h3>
<pre class="literal-block">
settings_pack <strong>get_settings</strong> () const;
void <strong>apply_settings</strong> (settings_pack const&amp; s);
</pre>
<p>Applies the settings specified by the <a class="reference external" href="reference-Settings.html#settings_pack">settings_pack</a> <tt class="docutils literal">s</tt>. This is an
asynchronous operation that will return immediately and actually apply
the settings to the main thread of libtorrent some time later.</p>
<a name="pop_alerts()"></a>
<a name="wait_for_alert()"></a>
<a name="set_alert_notify()"></a></div>
<div class="section" id="pop-alerts-wait-for-alert-set-alert-notify">
<h3>pop_alerts() wait_for_alert() set_alert_notify()</h3>
<pre class="literal-block">
void <strong>pop_alerts</strong> (std::vector&lt;alert*&gt;* alerts);
void <strong>set_alert_notify</strong> (boost::function&lt;void()&gt; const&amp; fun);
alert* <strong>wait_for_alert</strong> (time_duration max_wait);
</pre>
<p>Alerts is the main mechanism for libtorrent to report errors and
events. <tt class="docutils literal">pop_alerts</tt> fills in the vector passed to it with pointers
to new alerts. The <a class="reference external" href="reference-Core.html#session">session</a> still owns these alerts and they will stay
valid until the next time <tt class="docutils literal">pop_alerts</tt> is called. You may not delete
the <a class="reference external" href="reference-Alerts.html#alert">alert</a> objects.</p>
<p>It is safe to call <tt class="docutils literal">pop_alerts</tt> from multiple different threads, as
long as the alerts themselves are not accessed once another thread
calls <tt class="docutils literal">pop_alerts</tt>. Doing this requires manual synchronization
between the popping threads.</p>
<p><tt class="docutils literal">wait_for_alert</tt> will block the current thread for <tt class="docutils literal">max_wait</tt> time
duration, or until another <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted. If an <a class="reference external" href="reference-Alerts.html#alert">alert</a> is available
at the time of the call, it returns immediately. The returned <a class="reference external" href="reference-Alerts.html#alert">alert</a>
pointer is the head of the <a class="reference external" href="reference-Alerts.html#alert">alert</a> queue. <tt class="docutils literal">wait_for_alert</tt> does not
pop alerts from the queue, it merely peeks at it. The returned <a class="reference external" href="reference-Alerts.html#alert">alert</a>
will stay valid until <tt class="docutils literal">pop_alerts</tt> is called twice. The first time
will pop it and the second will free it.</p>
<p>If there is no <a class="reference external" href="reference-Alerts.html#alert">alert</a> in the queue and no <a class="reference external" href="reference-Alerts.html#alert">alert</a> arrives within the
specified timeout, <tt class="docutils literal">wait_for_alert</tt> returns NULL.</p>
<p>In the python binding, <tt class="docutils literal">wait_for_alert</tt> takes the number of
milliseconds to wait as an integer.</p>
<p>The <a class="reference external" href="reference-Alerts.html#alert">alert</a> queue in the <a class="reference external" href="reference-Core.html#session">session</a> will not grow indefinitely. Make sure
to pop periodically to not miss notifications. To control the max
number of alerts that's queued by the <a class="reference external" href="reference-Core.html#session">session</a>, see
<tt class="docutils literal"><span class="pre">settings_pack::alert_queue_size</span></tt>.</p>
<p>Some alerts are considered so important that they are posted even when
the <a class="reference external" href="reference-Alerts.html#alert">alert</a> queue is full. Some alerts are considered mandatory and cannot
be disabled by the <tt class="docutils literal">alert_mask</tt>. For instance,
<a class="reference external" href="reference-Alerts.html#save_resume_data_alert">save_resume_data_alert</a> and <a class="reference external" href="reference-Alerts.html#save_resume_data_failed_alert">save_resume_data_failed_alert</a> are always
posted, regardless of the <a class="reference external" href="reference-Alerts.html#alert">alert</a> mask.</p>
<p>To control which alerts are posted, set the alert_mask
(<a class="reference external" href="reference-Settings.html#alert_mask">settings_pack::alert_mask</a>).</p>
<p>the <tt class="docutils literal">set_alert_notify</tt> function lets the client set a function object
to be invoked every time the <a class="reference external" href="reference-Alerts.html#alert">alert</a> queue goes from having 0 alerts to
1 <a class="reference external" href="reference-Alerts.html#alert">alert</a>. This function is called from within libtorrent, it may be the
main thread, or it may be from within a user call. The intention of
of the function is that the client wakes up its main thread, to poll
for more alerts using <tt class="docutils literal">pop_alerts()</tt>. If the notify function fails
to do so, it won't be called again, until <tt class="docutils literal">pop_alerts</tt> is called for
some other reason. For instance, it could signal an eventfd, post a
message to an HWND or some other main message pump. The actual
retrieval of alerts should not be done in the callback. In fact, the
callback should not block. It should not perform any expensive work.
It really should just notify the main application thread.</p>
<a name="add_port_mapping()"></a>
<a name="delete_port_mapping()"></a></div>
<div class="section" id="add-port-mapping-delete-port-mapping">
<h3>add_port_mapping() delete_port_mapping()</h3>
<pre class="literal-block">
void <strong>delete_port_mapping</strong> (int handle);
int <strong>add_port_mapping</strong> (protocol_type t, int external_port, int local_port);
</pre>
<p>add_port_mapping adds a port forwarding on UPnP and/or NAT-PMP,
whichever is enabled. The return value is a handle referring to the
port mapping that was just created. Pass it to <a class="reference external" href="reference-Core.html#delete_port_mapping()">delete_port_mapping()</a>
to remove it.</p>
<a name="native_handle()"></a></div>
<div class="section" id="native-handle">
<h3>native_handle()</h3>
<pre class="literal-block">
aux::session_impl* <strong>native_handle</strong> () const;
</pre>
<p>This function is intended only for use by plugins. This type does
not have a stable API and should be relied on as little as possible.</p>
<a name="save_state_flags_t"></a></div>
<div class="section" id="enum-save-state-flags-t">
<h3>enum save_state_flags_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/session_handle.hpp">libtorrent/session_handle.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="21%" />
<col width="8%" />
<col width="72%" />
</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>save_settings</td>
<td>1</td>
<td>saves settings (i.e. the <a class="reference external" href="reference-Settings.html#settings_pack">settings_pack</a>)</td>
</tr>
<tr><td>save_dht_settings</td>
<td>2</td>
<td>saves <a class="reference external" href="reference-Settings.html#dht_settings">dht_settings</a></td>
</tr>
<tr><td>save_dht_state</td>
<td>4</td>
<td>saves dht state such as nodes and node-id, possibly accelerating
joining the DHT if provided at next <a class="reference external" href="reference-Core.html#session">session</a> startup.</td>
</tr>
</tbody>
</table>
<a name="options_t"></a></div>
<div class="section" id="enum-options-t">
<h3>enum options_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/session_handle.hpp">libtorrent/session_handle.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="21%" />
<col width="9%" />
<col width="70%" />
</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>delete_files</td>
<td>1</td>
<td>delete the files belonging to the torrent from disk.
including the part-file, if there is one</td>
</tr>
<tr><td>delete_partfile</td>
<td>2</td>
<td>delete just the part-file associated with this torrent</td>
</tr>
</tbody>
</table>
<a name="session_flags_t"></a></div>
<div class="section" id="enum-session-flags-t">
<h3>enum session_flags_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/session_handle.hpp">libtorrent/session_handle.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="25%" />
<col width="7%" />
<col width="68%" />
</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>add_default_plugins</td>
<td>1</td>
<td>this will add common extensions like ut_pex, ut_metadata, lt_tex
smart_ban and possibly others.</td>
</tr>
<tr><td>start_default_features</td>
<td>2</td>
<td>this will start features like DHT, local service discovery, UPnP
and NAT-PMP.</td>
</tr>
</tbody>
</table>
<a name="protocol_type"></a></div>
<div class="section" id="enum-protocol-type">
<h3>enum protocol_type</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/session_handle.hpp">libtorrent/session_handle.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="23%" />
<col width="27%" />
<col width="50%" />
</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>udp</td>
<td>1</td>
<td>&nbsp;</td>
</tr>
<tr><td>tcp</td>
<td>2</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<a name="session_proxy"></a></div>
</div>
<div class="section" id="session-proxy">
<h2>session_proxy</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/session.hpp">libtorrent/session.hpp</a>&quot;</p>
<p>this is a holder for the internal <a class="reference external" href="reference-Core.html#session">session</a> implementation object. Once the
<a class="reference external" href="reference-Core.html#session">session</a> destruction is explicitly initiated, this holder is used to
synchronize the completion of the shutdown. The lifetime of this object
may outlive <a class="reference external" href="reference-Core.html#session">session</a>, causing the <a class="reference external" href="reference-Core.html#session">session</a> destructor to not block. The
<a class="reference external" href="reference-Core.html#session_proxy">session_proxy</a> destructor will block however, until the underlying <a class="reference external" href="reference-Core.html#session">session</a>
is done shutting down.</p>
<pre class="literal-block">
class session_proxy
{
   <strong>~session_proxy</strong> ();
   <strong>session_proxy</strong> (session_proxy const&amp;) = default;
   session_proxy&amp; <strong>operator=</strong> (session_proxy const&amp;) = default;
   <strong>session_proxy</strong> ();
};
</pre>
<a name="session_proxy()"></a>
<a name="~session_proxy()"></a>
<a name="operator=()"></a><div class="section" id="session-proxy-session-proxy-operator">
<h3>session_proxy() ~session_proxy() operator=()</h3>
<pre class="literal-block">
<strong>~session_proxy</strong> ();
<strong>session_proxy</strong> (session_proxy const&amp;) = default;
session_proxy&amp; <strong>operator=</strong> (session_proxy const&amp;) = default;
<strong>session_proxy</strong> ();
</pre>
<p>default constructor, does not refer to any <a class="reference external" href="reference-Core.html#session">session</a>
implementation object.</p>
<a name="session"></a></div>
</div>
<div class="section" id="session">
<h2>session</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/session.hpp">libtorrent/session.hpp</a>&quot;</p>
<p>The <a class="reference external" href="reference-Core.html#session">session</a> holds all state that spans multiple torrents. Among other
things it runs the network loop and manages all torrents. Once it's
created, the <a class="reference external" href="reference-Core.html#session">session</a> object will spawn the main thread that will do all
the work. The main thread will be idle as long it doesn't have any
torrents to participate in.</p>
<p>You have some control over <a class="reference external" href="reference-Core.html#session">session</a> configuration through the
<tt class="docutils literal"><span class="pre">session::apply_settings()</span></tt> member function. To change one or more
configuration options, create a <a class="reference external" href="reference-Settings.html#settings_pack">settings_pack</a>. object and fill it with
the settings to be set and pass it in to <tt class="docutils literal"><span class="pre">session::apply_settings()</span></tt>.</p>
<p>see <a class="reference external" href="reference-Core.html#apply_settings()">apply_settings()</a>.</p>
<pre class="literal-block">
class session : public boost::noncopyable, public session_handle
{
   <strong>session</strong> (settings_pack const&amp; pack = settings_pack()
      , int flags = start_default_features | add_default_plugins);
   <strong>session</strong> (settings_pack const&amp; pack
      , io_service&amp; ios
      , int flags = start_default_features | add_default_plugins);
   <strong>~session</strong> ();
   session_proxy <strong>abort</strong> ();
};
</pre>
<a name="session()"></a><div class="section" id="id128">
<h3>session()</h3>
<pre class="literal-block">
<strong>session</strong> (settings_pack const&amp; pack = settings_pack()
      , int flags = start_default_features | add_default_plugins);
</pre>
<p>Constructs the <a class="reference external" href="reference-Core.html#session">session</a> objects which acts as the container of torrents.
It provides configuration options across torrents (such as rate limits,
disk cache, ip filter etc.). In order to avoid a race condition between
starting the <a class="reference external" href="reference-Core.html#session">session</a> and configuring it, you can pass in a
<a class="reference external" href="reference-Settings.html#settings_pack">settings_pack</a> object. Its settings will take effect before the <a class="reference external" href="reference-Core.html#session">session</a>
starts up.</p>
<p>The <tt class="docutils literal">flags</tt> parameter can be used to start default features (UPnP &amp;
NAT-PMP) and default plugins (ut_metadata, ut_pex and smart_ban). The
default is to start those features. If you do not want them to start,
pass 0 as the flags parameter.</p>
<a name="session()"></a></div>
<div class="section" id="id133">
<h3>session()</h3>
<pre class="literal-block">
<strong>session</strong> (settings_pack const&amp; pack
      , io_service&amp; ios
      , int flags = start_default_features | add_default_plugins);
</pre>
<p>overload of the constructor that takes an external io_service to run
the <a class="reference external" href="reference-Core.html#session">session</a> object on. This is primarily useful for tests that may want
to run multiple sessions on a single io_service, or low resource
systems where additional threads are expensive and sharing an
io_service with other events is fine.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The <a class="reference external" href="reference-Core.html#session">session</a> object does not cleanly terminate with an external
<tt class="docutils literal">io_service</tt>. The <tt class="docutils literal"><span class="pre">io_service::run()</span></tt> call _must_ have returned
before it's safe to destruct the <a class="reference external" href="reference-Core.html#session">session</a>. Which means you <em>MUST</em>
call <a class="reference external" href="reference-Core.html#abort()">session::abort()</a> and save the <a class="reference external" href="reference-Core.html#session_proxy">session_proxy</a> first, then
destruct the <a class="reference external" href="reference-Core.html#session">session</a> object, then sync with the io_service, then
destruct the <a class="reference external" href="reference-Core.html#session_proxy">session_proxy</a> object.</p>
</div>
<a name="~session()"></a></div>
<div class="section" id="id141">
<h3>~session()</h3>
<pre class="literal-block">
<strong>~session</strong> ();
</pre>
<p>The destructor of <a class="reference external" href="reference-Core.html#session">session</a> will notify all trackers that our torrents
have been shut down. If some trackers are down, they will time out.
All this before the destructor of <a class="reference external" href="reference-Core.html#session">session</a> returns. So, it's advised
that any kind of interface (such as windows) are closed before
destructing the <a class="reference external" href="reference-Core.html#session">session</a> object. Because it can take a few second for
it to finish. The timeout can be set with <a class="reference external" href="reference-Core.html#apply_settings()">apply_settings()</a>.</p>
<a name="abort()"></a></div>
<div class="section" id="abort">
<h3>abort()</h3>
<pre class="literal-block">
session_proxy <strong>abort</strong> ();
</pre>
<p>In case you want to destruct the <a class="reference external" href="reference-Core.html#session">session</a> asynchronously, you can
request a <a class="reference external" href="reference-Core.html#session">session</a> destruction proxy. If you don't do this, the
destructor of the <a class="reference external" href="reference-Core.html#session">session</a> object will block while the trackers are
contacted. If you keep one <tt class="docutils literal">session_proxy</tt> to the <a class="reference external" href="reference-Core.html#session">session</a> when
destructing it, the destructor will not block, but start to close down
the <a class="reference external" href="reference-Core.html#session">session</a>, the destructor of the proxy will then synchronize the
threads. So, the destruction of the <a class="reference external" href="reference-Core.html#session">session</a> is performed from the
<tt class="docutils literal">session</tt> destructor call until the <tt class="docutils literal">session_proxy</tt> destructor
call. The <tt class="docutils literal">session_proxy</tt> does not have any operations on it (since
the <a class="reference external" href="reference-Core.html#session">session</a> is being closed down, no operations are allowed on it).
The only valid operation is calling the destructor:</p>
<pre class="literal-block">
class session_proxy
{
public:
        session_proxy();
        ~session_proxy()
};
</pre>
<a name="bt_peer_connection_handle"></a></div>
</div>
<div class="section" id="bt-peer-connection-handle">
<h2>bt_peer_connection_handle</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/peer_connection_handle.hpp">libtorrent/peer_connection_handle.hpp</a>&quot;</p>
<pre class="literal-block">
struct bt_peer_connection_handle : public peer_connection_handle
{
   explicit <strong>bt_peer_connection_handle</strong> (peer_connection_handle pc);
   bool <strong>support_extensions</strong> () const;
   bool <strong>packet_finished</strong> () const;
   bool <strong>supports_encryption</strong> () const;
   void <strong>switch_recv_crypto</strong> (boost::shared_ptr&lt;crypto_plugin&gt; crypto);
   void <strong>switch_send_crypto</strong> (boost::shared_ptr&lt;crypto_plugin&gt; crypto);
   boost::shared_ptr&lt;bt_peer_connection&gt; <strong>native_handle</strong> () const;
};
</pre>
<a name="torrent_status"></a></div>
<div class="section" id="torrent-status">
<h2>torrent_status</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_status.hpp">libtorrent/torrent_status.hpp</a>&quot;</p>
<p>holds a snapshot of the status of a torrent, as queried by
<a class="reference external" href="reference-Core.html#status()">torrent_handle::status()</a>.</p>
<pre class="literal-block">
struct torrent_status
{
   bool <strong>operator==</strong> (torrent_status const&amp; st) const;

   enum state_t
   {
      checking_files,
      downloading_metadata,
      downloading,
      finished,
      seeding,
      allocating,
      checking_resume_data,
   };

   torrent_handle handle;
   std::string save_path;
   std::string name;
   boost::weak_ptr&lt;const torrent_info&gt; torrent_file;
   time_duration next_announce;
   std::string current_tracker;
   boost::int64_t total_download;
   boost::int64_t total_upload;
   boost::int64_t total_payload_download;
   boost::int64_t total_payload_upload;
   boost::int64_t total_failed_bytes;
   boost::int64_t total_redundant_bytes;
   bitfield pieces;
   bitfield verified_pieces;
   boost::int64_t total_done;
   boost::int64_t total_wanted_done;
   boost::int64_t total_wanted;
   boost::int64_t all_time_upload;
   boost::int64_t all_time_download;
   time_t added_time;
   time_t completed_time;
   time_t last_seen_complete;
   storage_mode_t storage_mode;
   float progress;
   int progress_ppm;
   int queue_position;
   int download_rate;
   int upload_rate;
   int download_payload_rate;
   int upload_payload_rate;
   int num_seeds;
   int num_peers;
   int num_complete;
   int num_incomplete;
   int list_seeds;
   int list_peers;
   int connect_candidates;
   int num_pieces;
   int distributed_full_copies;
   int distributed_fraction;
   float distributed_copies;
   int block_size;
   int num_uploads;
   int num_connections;
   int uploads_limit;
   int connections_limit;
   int up_bandwidth_queue;
   int down_bandwidth_queue;
   int time_since_upload;
   int time_since_download;
   int active_time;
   int finished_time;
   int seeding_time;
   int seed_rank;
   int last_scrape;
   int priority;
   state_t state;
   bool need_save_resume;
   bool ip_filter_applies;
   bool upload_mode;
   bool share_mode;
   bool super_seeding;
   bool paused;
   bool auto_managed;
   bool sequential_download;
   bool is_seeding;
   bool is_finished;
   bool has_metadata;
   bool has_incoming;
   bool seed_mode;
   bool moving_storage;
   bool is_loaded;
   bool announcing_to_trackers;
   bool announcing_to_lsd;
   bool announcing_to_dht;
   bool stop_when_ready;
   sha1_hash info_hash;
};
</pre>
<a name="operator==()"></a><div class="section" id="operator">
<h3>operator==()</h3>
<pre class="literal-block">
bool <strong>operator==</strong> (torrent_status const&amp; st) const;
</pre>
<p>compares if the torrent status objects come from the same torrent. i.e.
only the <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> field is compared.</p>
<a name="state_t"></a></div>
<div class="section" id="enum-state-t">
<h3>enum state_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_status.hpp">libtorrent/torrent_status.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="25%" />
<col width="8%" />
<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>checking_files</td>
<td>1</td>
<td>The torrent has not started its download yet, and is
currently checking existing files.</td>
</tr>
<tr><td>downloading_metadata</td>
<td>2</td>
<td>The torrent is trying to download metadata from peers.
This assumes the metadata_transfer extension is in use.</td>
</tr>
<tr><td>downloading</td>
<td>3</td>
<td>The torrent is being downloaded. This is the state
most torrents will be in most of the time. The progress
meter will tell how much of the files that has been
downloaded.</td>
</tr>
<tr><td>finished</td>
<td>4</td>
<td>In this state the torrent has finished downloading but
still doesn't have the entire torrent. i.e. some pieces
are filtered and won't get downloaded.</td>
</tr>
<tr><td>seeding</td>
<td>5</td>
<td>In this state the torrent has finished downloading and
is a pure seeder.</td>
</tr>
<tr><td>allocating</td>
<td>6</td>
<td>If the torrent was started in full allocation mode, this
indicates that the (disk) storage for the torrent is
allocated.</td>
</tr>
<tr><td>checking_resume_data</td>
<td>7</td>
<td>The torrent is currently checking the fastresume data and
comparing it to the files on disk. This is typically
completed in a fraction of a second, but if you add a
large number of torrents at once, they will queue up.</td>
</tr>
</tbody>
</table>
<a name="handle"></a><dl class="docutils">
<dt>handle</dt>
<dd>a handle to the torrent whose status the object represents.</dd>
</dl>
<a name="save_path"></a><dl class="docutils">
<dt>save_path</dt>
<dd>the path to the directory where this torrent's files are stored.
It's typically the path as was given to <a class="reference external" href="reference-Core.html#async_add_torrent()">async_add_torrent()</a> or
<a class="reference external" href="reference-Core.html#add_torrent()">add_torrent()</a> when this torrent was started. This field is only
included if the torrent status is queried with
<tt class="docutils literal"><span class="pre">torrent_handle::query_save_path</span></tt>.</dd>
</dl>
<a name="name"></a><dl class="docutils">
<dt>name</dt>
<dd>the name of the torrent. Typically this is derived from the
.torrent file. In case the torrent was started without metadata,
and hasn't completely received it yet, it returns the name given
to it when added to the <a class="reference external" href="reference-Core.html#session">session</a>. See <tt class="docutils literal"><span class="pre">session::add_torrent</span></tt>.
This field is only included if the torrent status is queried
with <tt class="docutils literal"><span class="pre">torrent_handle::query_name</span></tt>.</dd>
</dl>
<a name="torrent_file"></a><dl class="docutils">
<dt>torrent_file</dt>
<dd>set to point to the <tt class="docutils literal">torrent_info</tt> object for this torrent. It's
only included if the torrent status is queried with
<tt class="docutils literal"><span class="pre">torrent_handle::query_torrent_file</span></tt>.</dd>
</dl>
<a name="next_announce"></a><dl class="docutils">
<dt>next_announce</dt>
<dd>the time until the torrent will announce itself to the tracker.</dd>
</dl>
<a name="current_tracker"></a><dl class="docutils">
<dt>current_tracker</dt>
<dd>the URL of the last working tracker. If no tracker request has
been successful yet, it's set to an empty string.</dd>
</dl>
<a name="total_download"></a>
<a name="total_upload"></a><dl class="docutils">
<dt>total_download  total_upload</dt>
<dd>the number of bytes downloaded and uploaded to all peers, accumulated,
<em>this session</em> only. The <a class="reference external" href="reference-Core.html#session">session</a> is considered to restart when a
torrent is paused and restarted again. When a torrent is paused, these
counters are reset to 0. If you want complete, persistent, stats, see
<tt class="docutils literal">all_time_upload</tt> and <tt class="docutils literal">all_time_download</tt>.</dd>
</dl>
<a name="total_payload_download"></a>
<a name="total_payload_upload"></a><dl class="docutils">
<dt>total_payload_download  total_payload_upload</dt>
<dd>counts the amount of bytes send and received this <a class="reference external" href="reference-Core.html#session">session</a>, but only
the actual payload data (i.e the interesting data), these counters
ignore any protocol overhead. The <a class="reference external" href="reference-Core.html#session">session</a> is considered to restart
when a torrent is paused and restarted again. When a torrent is
paused, these counters are reset to 0.</dd>
</dl>
<a name="total_failed_bytes"></a><dl class="docutils">
<dt>total_failed_bytes</dt>
<dd>the number of bytes that has been downloaded and that has failed the
piece hash test. In other words, this is just how much crap that has
been downloaded since the torrent was last started. If a torrent is
paused and then restarted again, this counter will be reset.</dd>
</dl>
<a name="total_redundant_bytes"></a><dl class="docutils">
<dt>total_redundant_bytes</dt>
<dd>the number of bytes that has been downloaded even though that data
already was downloaded. The reason for this is that in some situations
the same data can be downloaded by mistake. When libtorrent sends
requests to a peer, and the peer doesn't send a response within a
certain timeout, libtorrent will re-request that block. Another
situation when libtorrent may re-request blocks is when the requests
it sends out are not replied in FIFO-order (it will re-request blocks
that are skipped by an out of order block). This is supposed to be as
low as possible. This only counts bytes since the torrent was last
started. If a torrent is paused and then restarted again, this counter
will be reset.</dd>
</dl>
<a name="pieces"></a><dl class="docutils">
<dt>pieces</dt>
<dd>a bitmask that represents which pieces we have (set to true) and the
pieces we don't have. It's a pointer and may be set to 0 if the
torrent isn't downloading or seeding.</dd>
</dl>
<a name="verified_pieces"></a><dl class="docutils">
<dt>verified_pieces</dt>
<dd>a bitmask representing which pieces has had their hash checked. This
only applies to torrents in <em>seed mode</em>. If the torrent is not in seed
mode, this bitmask may be empty.</dd>
</dl>
<a name="total_done"></a><dl class="docutils">
<dt>total_done</dt>
<dd>the total number of bytes of the file(s) that we have. All this does
not necessarily has to be downloaded during this <a class="reference external" href="reference-Core.html#session">session</a> (that's
<tt class="docutils literal">total_payload_download</tt>).</dd>
</dl>
<a name="total_wanted_done"></a><dl class="docutils">
<dt>total_wanted_done</dt>
<dd>the number of bytes we have downloaded, only counting the pieces that
we actually want to download. i.e. excluding any pieces that we have
but have priority 0 (i.e. not wanted).</dd>
</dl>
<a name="total_wanted"></a><dl class="docutils">
<dt>total_wanted</dt>
<dd>The total number of bytes we want to download. This may be smaller
than the total torrent size in case any pieces are prioritized to 0,
i.e.  not wanted</dd>
</dl>
<a name="all_time_upload"></a>
<a name="all_time_download"></a><dl class="docutils">
<dt>all_time_upload  all_time_download</dt>
<dd>are accumulated upload and download payload byte counters. They are
saved in and restored from resume data to keep totals across sessions.</dd>
</dl>
<a name="added_time"></a><dl class="docutils">
<dt>added_time</dt>
<dd>the posix-time when this torrent was added. i.e. what <tt class="docutils literal">time(NULL)</tt>
returned at the time.</dd>
</dl>
<a name="completed_time"></a><dl class="docutils">
<dt>completed_time</dt>
<dd>the posix-time when this torrent was finished. If the torrent is not
yet finished, this is 0.</dd>
</dl>
<a name="last_seen_complete"></a><dl class="docutils">
<dt>last_seen_complete</dt>
<dd>the time when we, or one of our peers, last saw a complete copy of
this torrent.</dd>
</dl>
<a name="storage_mode"></a><dl class="docutils">
<dt>storage_mode</dt>
<dd>The allocation mode for the torrent. See <a class="reference external" href="reference-Storage.html#storage_mode_t">storage_mode_t</a> for the
options. For more information, see <a class="reference external" href="manual-ref.html#storage-allocation">storage allocation</a>.</dd>
</dl>
<a name="progress"></a><dl class="docutils">
<dt>progress</dt>
<dd>a value in the range [0, 1], that represents the progress of the
torrent's current task. It may be checking files or downloading.</dd>
</dl>
<a name="progress_ppm"></a><dl class="docutils">
<dt>progress_ppm</dt>
<dd><p class="first">progress parts per million (progress * 1000000) when disabling
floating point operations, this is the only option to query progress</p>
<p class="last">reflects the same value as <tt class="docutils literal">progress</tt>, but instead in a range [0,
1000000] (ppm = parts per million). When floating point operations are
disabled, this is the only alternative to the floating point value in
progress.</p>
</dd>
</dl>
<a name="queue_position"></a><dl class="docutils">
<dt>queue_position</dt>
<dd>the position this torrent has in the download
queue. If the torrent is a seed or finished, this is -1.</dd>
</dl>
<a name="download_rate"></a>
<a name="upload_rate"></a><dl class="docutils">
<dt>download_rate  upload_rate</dt>
<dd>the total rates for all peers for this torrent. These will usually
have better precision than summing the rates from all peers. The rates
are given as the number of bytes per second.</dd>
</dl>
<a name="download_payload_rate"></a>
<a name="upload_payload_rate"></a><dl class="docutils">
<dt>download_payload_rate  upload_payload_rate</dt>
<dd>the total transfer rate of payload only, not counting protocol
chatter. This might be slightly smaller than the other rates, but if
projected over a long time (e.g. when calculating ETA:s) the
difference may be noticeable.</dd>
</dl>
<a name="num_seeds"></a><dl class="docutils">
<dt>num_seeds</dt>
<dd>the number of peers that are seeding that this client is
currently connected to.</dd>
</dl>
<a name="num_peers"></a><dl class="docutils">
<dt>num_peers</dt>
<dd>the number of peers this torrent currently is connected to. Peer
connections that are in the half-open state (is attempting to connect)
or are queued for later connection attempt do not count. Although they
are visible in the peer list when you call <a class="reference external" href="reference-Core.html#get_peer_info()">get_peer_info()</a>.</dd>
</dl>
<a name="num_complete"></a>
<a name="num_incomplete"></a><dl class="docutils">
<dt>num_complete  num_incomplete</dt>
<dd>if the tracker sends scrape info in its announce reply, these fields
will be set to the total number of peers that have the whole file and
the total number of peers that are still downloading. set to -1 if the
tracker did not send any scrape data in its announce reply.</dd>
</dl>
<a name="list_seeds"></a>
<a name="list_peers"></a><dl class="docutils">
<dt>list_seeds  list_peers</dt>
<dd>the number of seeds in our peer list and the total number of peers
(including seeds). We are not necessarily connected to all the peers
in our peer list. This is the number of peers we know of in total,
including banned peers and peers that we have failed to connect to.</dd>
</dl>
<a name="connect_candidates"></a><dl class="docutils">
<dt>connect_candidates</dt>
<dd>the number of peers in this torrent's peer list that is a candidate to
be connected to. i.e. It has fewer connect attempts than the max fail
count, it is not a seed if we are a seed, it is not banned etc. If
this is 0, it means we don't know of any more peers that we can try.</dd>
</dl>
<a name="num_pieces"></a><dl class="docutils">
<dt>num_pieces</dt>
<dd>the number of pieces that has been downloaded. It is equivalent to:
<tt class="docutils literal"><span class="pre">std::accumulate(pieces-&gt;begin(),</span> <span class="pre">pieces-&gt;end())</span></tt>. So you don't have
to count yourself. This can be used to see if anything has updated
since last time if you want to keep a graph of the pieces up to date.</dd>
</dl>
<a name="distributed_full_copies"></a><dl class="docutils">
<dt>distributed_full_copies</dt>
<dd>the number of distributed copies of the torrent. Note that one copy
may be spread out among many peers. It tells how many copies there are
currently of the rarest piece(s) among the peers this client is
connected to.</dd>
</dl>
<a name="distributed_fraction"></a><dl class="docutils">
<dt>distributed_fraction</dt>
<dd><p class="first">tells the share of pieces that have more copies than the rarest
piece(s). Divide this number by 1000 to get the fraction.</p>
<p>For example, if <tt class="docutils literal">distributed_full_copies</tt> is 2 and
<tt class="docutils literal">distributed_fraction</tt> is 500, it means that the rarest pieces have
only 2 copies among the peers this torrent is connected to, and that
50% of all the pieces have more than two copies.</p>
<p class="last">If we are a seed, the piece picker is deallocated as an optimization,
and piece availability is no longer tracked. In this case the
distributed copies members are set to -1.</p>
</dd>
</dl>
<a name="distributed_copies"></a><dl class="docutils">
<dt>distributed_copies</dt>
<dd><p class="first">the number of distributed copies of the file. note that one copy may
be spread out among many peers. This is a floating point
representation of the distributed copies.</p>
<dl class="last docutils">
<dt>the integer part tells how many copies</dt>
<dd>there are of the rarest piece(s)</dd>
<dt>the fractional part tells the fraction of pieces that</dt>
<dd>have more copies than the rarest piece(s).</dd>
</dl>
</dd>
</dl>
<a name="block_size"></a><dl class="docutils">
<dt>block_size</dt>
<dd>the size of a block, in bytes. A block is a sub piece, it is the
number of bytes that each piece request asks for and the number of
bytes that each bit in the <tt class="docutils literal">partial_piece_info</tt>'s bitset represents,
see <a class="reference external" href="reference-Core.html#get_download_queue()">get_download_queue()</a>. This is typically 16 kB, but it may be
larger if the pieces are larger.</dd>
</dl>
<a name="num_uploads"></a><dl class="docutils">
<dt>num_uploads</dt>
<dd>the number of unchoked peers in this torrent.</dd>
</dl>
<a name="num_connections"></a><dl class="docutils">
<dt>num_connections</dt>
<dd>the number of peer connections this torrent has, including half-open
connections that hasn't completed the bittorrent handshake yet. This
is always &gt;= <tt class="docutils literal">num_peers</tt>.</dd>
</dl>
<a name="uploads_limit"></a><dl class="docutils">
<dt>uploads_limit</dt>
<dd>the set limit of upload slots (unchoked peers) for this torrent.</dd>
</dl>
<a name="connections_limit"></a><dl class="docutils">
<dt>connections_limit</dt>
<dd>the set limit of number of connections for this torrent.</dd>
</dl>
<a name="up_bandwidth_queue"></a>
<a name="down_bandwidth_queue"></a><dl class="docutils">
<dt>up_bandwidth_queue  down_bandwidth_queue</dt>
<dd>the number of peers in this torrent that are waiting for more
bandwidth quota from the torrent rate limiter. This can determine if
the rate you get from this torrent is bound by the torrents limit or
not. If there is no limit set on this torrent, the peers might still
be waiting for bandwidth quota from the global limiter, but then they
are counted in the <tt class="docutils literal">session_status</tt> object.</dd>
</dl>
<a name="time_since_upload"></a>
<a name="time_since_download"></a><dl class="docutils">
<dt>time_since_upload  time_since_download</dt>
<dd>the number of seconds since any peer last uploaded from this torrent
and the last time a downloaded piece passed the hash check,
respectively. Note, when starting up a torrent that needs its files
checked, piece may pass and that will be considered downloading for the
purpose of this counter. -1 means there either hasn't been any
uploading/downloading, or it was too long ago for libtorrent to
remember (currently forgetting happens after about 18 hours)</dd>
</dl>
<a name="active_time"></a>
<a name="finished_time"></a>
<a name="seeding_time"></a><dl class="docutils">
<dt>active_time  finished_time  seeding_time</dt>
<dd>These keep track of the number of seconds this torrent has been active
(not paused) and the number of seconds it has been active while being
finished and active while being a seed. <tt class="docutils literal">seeding_time</tt> should be &lt;=
<tt class="docutils literal">finished_time</tt> which should be &lt;= <tt class="docutils literal">active_time</tt>. They are all
saved in and restored from resume data, to keep totals across
sessions.</dd>
</dl>
<a name="seed_rank"></a><dl class="docutils">
<dt>seed_rank</dt>
<dd>A rank of how important it is to seed the torrent, it is used to
determine which torrents to seed and which to queue. It is based on
the peer to seed ratio from the tracker scrape. For more information,
see <a class="reference external" href="manual-ref.html#queuing">queuing</a>. Higher value means more important to seed</dd>
</dl>
<a name="last_scrape"></a><dl class="docutils">
<dt>last_scrape</dt>
<dd>the number of seconds since this torrent acquired scrape data.
If it has never done that, this value is -1.</dd>
</dl>
<a name="priority"></a><dl class="docutils">
<dt>priority</dt>
<dd>the priority of this torrent</dd>
</dl>
<a name="state"></a><dl class="docutils">
<dt>state</dt>
<dd>the main state the torrent is in. See <a class="reference external" href="reference-Core.html#state_t">torrent_status::state_t</a>.</dd>
</dl>
<a name="need_save_resume"></a><dl class="docutils">
<dt>need_save_resume</dt>
<dd>true if this torrent has unsaved changes
to its download state and statistics since the last resume data
was saved.</dd>
</dl>
<a name="ip_filter_applies"></a><dl class="docutils">
<dt>ip_filter_applies</dt>
<dd>true if the <a class="reference external" href="reference-Core.html#session">session</a> global IP filter applies
to this torrent. This defaults to true.</dd>
</dl>
<a name="upload_mode"></a><dl class="docutils">
<dt>upload_mode</dt>
<dd>true if the torrent is blocked from downloading. This typically
happens when a disk write operation fails. If the torrent is
auto-managed, it will periodically be taken out of this state, in the
hope that the disk condition (be it disk full or permission errors)
has been resolved. If the torrent is not auto-managed, you have to
explicitly take it out of the upload mode by calling <a class="reference external" href="reference-Core.html#set_upload_mode()">set_upload_mode()</a>
on the <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a>.</dd>
</dl>
<a name="share_mode"></a><dl class="docutils">
<dt>share_mode</dt>
<dd>true if the torrent is currently in share-mode, i.e. not downloading
the torrent, but just helping the swarm out.</dd>
</dl>
<a name="super_seeding"></a><dl class="docutils">
<dt>super_seeding</dt>
<dd>true if the torrent is in super seeding mode</dd>
</dl>
<a name="paused"></a><dl class="docutils">
<dt>paused</dt>
<dd>set to true if the torrent is paused and false otherwise. It's only
true if the torrent itself is paused. If the torrent is not running
because the <a class="reference external" href="reference-Core.html#session">session</a> is paused, this is still false. To know if a
torrent is active or not, you need to inspect both
<tt class="docutils literal"><span class="pre">torrent_status::paused</span></tt> and <tt class="docutils literal"><span class="pre">session::is_paused()</span></tt>.</dd>
</dl>
<a name="auto_managed"></a><dl class="docutils">
<dt>auto_managed</dt>
<dd>set to true if the torrent is auto managed, i.e. libtorrent is
responsible for determining whether it should be started or queued.
For more info see <a class="reference external" href="manual-ref.html#queuing">queuing</a></dd>
</dl>
<a name="sequential_download"></a><dl class="docutils">
<dt>sequential_download</dt>
<dd>true when the torrent is in sequential download mode. In this mode
pieces are downloaded in order rather than rarest first.</dd>
</dl>
<a name="is_seeding"></a><dl class="docutils">
<dt>is_seeding</dt>
<dd>true if all pieces have been downloaded.</dd>
</dl>
<a name="is_finished"></a><dl class="docutils">
<dt>is_finished</dt>
<dd>true if all pieces that have a priority &gt; 0 are downloaded. There is
only a distinction between finished and seeding if some pieces or
files have been set to priority 0, i.e. are not downloaded.</dd>
</dl>
<a name="has_metadata"></a><dl class="docutils">
<dt>has_metadata</dt>
<dd>true if this torrent has metadata (either it was started from a
.torrent file or the metadata has been downloaded). The only scenario
where this can be false is when the torrent was started torrent-less
(i.e. with just an info-hash and tracker ip, a magnet link for
instance).</dd>
</dl>
<a name="has_incoming"></a><dl class="docutils">
<dt>has_incoming</dt>
<dd>true if there has ever been an incoming connection attempt to this
torrent.</dd>
</dl>
<a name="seed_mode"></a><dl class="docutils">
<dt>seed_mode</dt>
<dd>true if the torrent is in seed_mode. If the torrent was started in
seed mode, it will leave seed mode once all pieces have been checked
or as soon as one piece fails the hash check.</dd>
</dl>
<a name="moving_storage"></a><dl class="docutils">
<dt>moving_storage</dt>
<dd>this is true if this torrent's storage is currently being moved from
one location to another. This may potentially be a long operation
if a large file ends up being copied from one drive to another.</dd>
</dl>
<a name="is_loaded"></a><dl class="docutils">
<dt>is_loaded</dt>
<dd>true if this torrent is loaded into RAM. A torrent can be started
and still not loaded into RAM, in case it has not had any peers interested in it
yet. Torrents are loaded on demand.</dd>
</dl>
<a name="announcing_to_trackers"></a>
<a name="announcing_to_lsd"></a>
<a name="announcing_to_dht"></a><dl class="docutils">
<dt>announcing_to_trackers  announcing_to_lsd  announcing_to_dht</dt>
<dd>these are set to true if this torrent is allowed to announce to the
respective peer source. Whether they are true or false is determined by
the queue logic/auto manager. Torrents that are not auto managed will
always be allowed to announce to all peer sources.</dd>
</dl>
<a name="stop_when_ready"></a><dl class="docutils">
<dt>stop_when_ready</dt>
<dd>this reflects whether the <tt class="docutils literal">stop_when_ready</tt> flag is currently enabled
on this torrent. For more information, see
<a class="reference external" href="reference-Core.html#stop_when_ready()">torrent_handle::stop_when_ready()</a>.</dd>
</dl>
<a name="info_hash"></a><dl class="docutils">
<dt>info_hash</dt>
<dd>the info-hash for this torrent</dd>
</dl>
<a name="announce_entry"></a></div>
</div>
<div class="section" id="announce-entry">
<h2>announce_entry</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/announce_entry.hpp">libtorrent/announce_entry.hpp</a>&quot;</p>
<p>this class holds information about one bittorrent tracker, as it
relates to a specific torrent.</p>
<pre class="literal-block">
struct announce_entry
{
   <strong>announce_entry</strong> (std::string const&amp; u);
   <strong>announce_entry</strong> (announce_entry const&amp;) = default;
   <strong>~announce_entry</strong> ();
   announce_entry&amp; <strong>operator=</strong> (announce_entry const&amp;) = default;
   <strong>announce_entry</strong> ();
   int <strong>next_announce_in</strong> () const;
   int <strong>min_announce_in</strong> () const;
   void <strong>reset</strong> ();
   void <strong>failed</strong> (aux::session_settings const&amp; sett, int retry_interval = 0);
   bool <strong>can_announce</strong> (time_point now, bool is_seed) const;
   bool <strong>is_working</strong> () const;
   void <strong>trim</strong> ();

   enum tracker_source
   {
      source_torrent,
      source_client,
      source_magnet_link,
      source_tex,
   };

   std::string url;
   std::string trackerid;
   std::string message;
   error_code last_error;
   time_point next_announce;
   time_point min_announce;
   int scrape_incomplete;
   int scrape_complete;
   int scrape_downloaded;
   boost::uint8_t tier;
   boost::uint8_t fail_limit;
   boost::uint8_t fails:7;
   bool updating:1;
   boost::uint8_t source:4;
   bool verified:1;
   bool start_sent:1;
   bool complete_sent:1;
   bool send_stats:1;
};
</pre>
<a name="announce_entry()"></a>
<a name="~announce_entry()"></a>
<a name="operator=()"></a><div class="section" id="announce-entry-announce-entry-operator">
<h3>announce_entry() ~announce_entry() operator=()</h3>
<pre class="literal-block">
<strong>announce_entry</strong> (std::string const&amp; u);
<strong>announce_entry</strong> (announce_entry const&amp;) = default;
<strong>~announce_entry</strong> ();
announce_entry&amp; <strong>operator=</strong> (announce_entry const&amp;) = default;
<strong>announce_entry</strong> ();
</pre>
<p>constructs a tracker announce <a class="reference external" href="reference-Bencoding.html#entry">entry</a> with <tt class="docutils literal">u</tt> as the URL.</p>
<a name="min_announce_in()"></a>
<a name="next_announce_in()"></a></div>
<div class="section" id="min-announce-in-next-announce-in">
<h3>min_announce_in() next_announce_in()</h3>
<pre class="literal-block">
int <strong>next_announce_in</strong> () const;
int <strong>min_announce_in</strong> () const;
</pre>
<p>returns the number of seconds to the next announce on this tracker.
<tt class="docutils literal">min_announce_in()</tt> returns the number of seconds until we are
allowed to force another tracker update with this tracker.</p>
<p>If the last time this tracker was contacted failed, <tt class="docutils literal">last_error</tt> is
the error code describing what error occurred.</p>
<a name="reset()"></a></div>
<div class="section" id="reset">
<h3>reset()</h3>
<pre class="literal-block">
void <strong>reset</strong> ();
</pre>
<p>reset announce counters and clears the started sent flag.
The <a class="reference external" href="reference-Core.html#announce_entry">announce_entry</a> will look like we've never talked to
the tracker.</p>
<a name="failed()"></a></div>
<div class="section" id="failed">
<h3>failed()</h3>
<pre class="literal-block">
void <strong>failed</strong> (aux::session_settings const&amp; sett, int retry_interval = 0);
</pre>
<p>updates the failure counter and time-outs for re-trying.
This is called when the tracker announce fails.</p>
<a name="can_announce()"></a></div>
<div class="section" id="can-announce">
<h3>can_announce()</h3>
<pre class="literal-block">
bool <strong>can_announce</strong> (time_point now, bool is_seed) const;
</pre>
<p>returns true if we can announce to this tracker now.
The current time is passed in as <tt class="docutils literal">now</tt>. The <tt class="docutils literal">is_seed</tt>
argument is necessary because once we become a seed, we
need to announce right away, even if the re-announce timer
hasn't expired yet.</p>
<a name="is_working()"></a></div>
<div class="section" id="is-working">
<h3>is_working()</h3>
<pre class="literal-block">
bool <strong>is_working</strong> () const;
</pre>
<p>returns true if the last time we tried to announce to this
tracker succeeded, or if we haven't tried yet.</p>
<a name="trim()"></a></div>
<div class="section" id="trim">
<h3>trim()</h3>
<pre class="literal-block">
void <strong>trim</strong> ();
</pre>
<p>trims whitespace characters from the beginning of the URL.</p>
<a name="tracker_source"></a></div>
<div class="section" id="enum-tracker-source">
<h3>enum tracker_source</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/announce_entry.hpp">libtorrent/announce_entry.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="7%" />
<col width="73%" />
</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>source_torrent</td>
<td>1</td>
<td>the tracker was part of the .torrent file</td>
</tr>
<tr><td>source_client</td>
<td>2</td>
<td>the tracker was added programatically via the add_troacker()_ function</td>
</tr>
<tr><td>source_magnet_link</td>
<td>4</td>
<td>the tracker was part of a magnet link</td>
</tr>
<tr><td>source_tex</td>
<td>8</td>
<td>the tracker was received from the swarm via tracker exchange</td>
</tr>
</tbody>
</table>
<a name="url"></a><dl class="docutils">
<dt>url</dt>
<dd>tracker URL as it appeared in the torrent file</dd>
</dl>
<a name="trackerid"></a><dl class="docutils">
<dt>trackerid</dt>
<dd>the current <tt class="docutils literal">&amp;trackerid=</tt> argument passed to the tracker.
this is optional and is normally empty (in which case no
trackerid is sent).</dd>
</dl>
<a name="message"></a><dl class="docutils">
<dt>message</dt>
<dd>if this tracker has returned an error or warning message
that message is stored here</dd>
</dl>
<a name="last_error"></a><dl class="docutils">
<dt>last_error</dt>
<dd>if this tracker failed the last time it was contacted
this error code specifies what error occurred</dd>
</dl>
<a name="next_announce"></a><dl class="docutils">
<dt>next_announce</dt>
<dd>the time of next tracker announce</dd>
</dl>
<a name="min_announce"></a><dl class="docutils">
<dt>min_announce</dt>
<dd>no announces before this time</dd>
</dl>
<a name="scrape_incomplete"></a>
<a name="scrape_complete"></a>
<a name="scrape_downloaded"></a><dl class="docutils">
<dt>scrape_incomplete  scrape_complete  scrape_downloaded</dt>
<dd>if this tracker has returned scrape data, these fields are filled in
with valid numbers. Otherwise they are set to -1. the number of
current downloaders</dd>
</dl>
<a name="tier"></a><dl class="docutils">
<dt>tier</dt>
<dd>the tier this tracker belongs to</dd>
</dl>
<a name="fail_limit"></a><dl class="docutils">
<dt>fail_limit</dt>
<dd>the max number of failures to announce to this tracker in
a row, before this tracker is not used anymore. 0 means unlimited</dd>
</dl>
<a name="fails"></a><dl class="docutils">
<dt>fails</dt>
<dd>the number of times in a row we have failed to announce to this
tracker.</dd>
</dl>
<a name="updating"></a><dl class="docutils">
<dt>updating</dt>
<dd>true while we're waiting for a response from the tracker.</dd>
</dl>
<a name="source"></a><dl class="docutils">
<dt>source</dt>
<dd>a bitmask specifying which sources we got this tracker from.</dd>
</dl>
<a name="verified"></a><dl class="docutils">
<dt>verified</dt>
<dd>set to true the first time we receive a valid response
from this tracker.</dd>
</dl>
<a name="start_sent"></a><dl class="docutils">
<dt>start_sent</dt>
<dd>set to true when we get a valid response from an announce
with event=started. If it is set, we won't send start in the subsequent
announces.</dd>
</dl>
<a name="complete_sent"></a><dl class="docutils">
<dt>complete_sent</dt>
<dd>set to true when we send a event=completed.</dd>
</dl>
<a name="send_stats"></a><dl class="docutils">
<dt>send_stats</dt>
<dd>this is false the stats sent to this tracker will be 0</dd>
</dl>
<a name="peer_class_type_filter"></a></div>
</div>
<div class="section" id="peer-class-type-filter">
<h2>peer_class_type_filter</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/peer_class_type_filter.hpp">libtorrent/peer_class_type_filter.hpp</a>&quot;</p>
<p><tt class="docutils literal">peer_class_type_filter</tt> is a simple container for rules for adding and subtracting
peer-classes from peers. It is applied <em>after</em> the peer class filter is applied (which
is based on the peer's IP address).</p>
<pre class="literal-block">
struct peer_class_type_filter
{
   <strong>peer_class_type_filter</strong> ();
   void <strong>remove</strong> (socket_type_t st, peer_class_t peer_class);
   void <strong>add</strong> (socket_type_t st, peer_class_t peer_class);
   void <strong>disallow</strong> (socket_type_t st, peer_class_t peer_class);
   void <strong>allow</strong> (socket_type_t st, peer_class_t peer_class);
   boost::uint32_t <strong>apply</strong> (int st, boost::uint32_t peer_class_mask);

   enum socket_type_t
   {
      tcp_socket,
      utp_socket,
      ssl_tcp_socket,
      ssl_utp_socket,
      i2p_socket,
      num_socket_types,
   };
};
</pre>
<a name="remove()"></a>
<a name="add()"></a><div class="section" id="remove-add">
<h3>remove() add()</h3>
<pre class="literal-block">
void <strong>remove</strong> (socket_type_t st, peer_class_t peer_class);
void <strong>add</strong> (socket_type_t st, peer_class_t peer_class);
</pre>
<p><tt class="docutils literal">add()</tt> and <tt class="docutils literal">remove()</tt> adds and removes a peer class to be added
to new peers based on socket type.</p>
<a name="disallow()"></a>
<a name="allow()"></a></div>
<div class="section" id="disallow-allow">
<h3>disallow() allow()</h3>
<pre class="literal-block">
void <strong>disallow</strong> (socket_type_t st, peer_class_t peer_class);
void <strong>allow</strong> (socket_type_t st, peer_class_t peer_class);
</pre>
<p><tt class="docutils literal">disallow()</tt> and <tt class="docutils literal">allow()</tt> adds and removes a peer class to be
removed from new peers based on socket type.</p>
<p>The <tt class="docutils literal">peer_class</tt> argument cannot be greater than 31. The bitmasks representing
peer classes in the <tt class="docutils literal">peer_class_type_filter</tt> are 32 bits.</p>
<a name="apply()"></a></div>
<div class="section" id="apply">
<h3>apply()</h3>
<pre class="literal-block">
boost::uint32_t <strong>apply</strong> (int st, boost::uint32_t peer_class_mask);
</pre>
<p>takes a bitmask of peer classes and returns a new bitmask of
peer classes after the rules have been applied, based on the socket type argument
(<tt class="docutils literal">st</tt>).</p>
<a name="socket_type_t"></a></div>
<div class="section" id="enum-socket-type-t">
<h3>enum socket_type_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/peer_class_type_filter.hpp">libtorrent/peer_class_type_filter.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="24%" />
<col width="9%" />
<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>tcp_socket</td>
<td>0</td>
<td>these match the socket types from socket_type.hpp
shifted one down</td>
</tr>
<tr><td>utp_socket</td>
<td>1</td>
<td>&nbsp;</td>
</tr>
<tr><td>ssl_tcp_socket</td>
<td>2</td>
<td>&nbsp;</td>
</tr>
<tr><td>ssl_utp_socket</td>
<td>3</td>
<td>&nbsp;</td>
</tr>
<tr><td>i2p_socket</td>
<td>4</td>
<td>&nbsp;</td>
</tr>
<tr><td>num_socket_types</td>
<td>5</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<a name="block_info"></a></div>
</div>
<div class="section" id="block-info">
<h2>block_info</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p>
<p>holds the state of a block in a piece. Who we requested
it from and how far along we are at downloading it.</p>
<pre class="literal-block">
struct block_info
{
   void <strong>set_peer</strong> (tcp::endpoint const&amp; ep);
   <a class="reference external" href="tcp::endpoint">tcp::endpoint</a> <strong>peer</strong> () const;

   enum block_state_t
   {
      none,
      requested,
      writing,
      finished,
   };

   unsigned bytes_progress:15;
   unsigned block_size:15;
   unsigned state:2;
   unsigned num_peers:14;
};
</pre>
<a name="set_peer()"></a>
<a name="peer()"></a><div class="section" id="set-peer-peer">
<h3>set_peer() peer()</h3>
<pre class="literal-block">
void <strong>set_peer</strong> (tcp::endpoint const&amp; ep);
<a class="reference external" href="tcp::endpoint">tcp::endpoint</a> <strong>peer</strong> () const;
</pre>
<p>The peer is the ip address of the peer this block was downloaded from.</p>
<a name="block_state_t"></a></div>
<div class="section" id="enum-block-state-t">
<h3>enum block_state_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="13%" />
<col width="8%" />
<col width="79%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">value</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>none</td>
<td>0</td>
<td>This block has not been downloaded or requested form any peer.</td>
</tr>
<tr><td>requested</td>
<td>1</td>
<td>The block has been requested, but not completely downloaded yet.</td>
</tr>
<tr><td>writing</td>
<td>2</td>
<td>The block has been downloaded and is currently queued for being
written to disk.</td>
</tr>
<tr><td>finished</td>
<td>3</td>
<td>The block has been written to disk.</td>
</tr>
</tbody>
</table>
<a name="bytes_progress"></a><dl class="docutils">
<dt>bytes_progress</dt>
<dd>the number of bytes that have been received for this block</dd>
</dl>
<a name="block_size"></a><dl class="docutils">
<dt>block_size</dt>
<dd>the total number of bytes in this block.</dd>
</dl>
<a name="state"></a><dl class="docutils">
<dt>state</dt>
<dd>the state this block is in (see <a class="reference external" href="reference-Core.html#block_state_t">block_state_t</a>)</dd>
</dl>
<a name="num_peers"></a><dl class="docutils">
<dt>num_peers</dt>
<dd>the number of peers that is currently requesting this block. Typically
this is 0 or 1, but at the end of the torrent blocks may be requested
by more peers in parallel to speed things up.</dd>
</dl>
<a name="partial_piece_info"></a></div>
</div>
<div class="section" id="partial-piece-info">
<h2>partial_piece_info</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p>
<p>This class holds information about pieces that have outstanding requests
or outstanding writes</p>
<pre class="literal-block">
struct partial_piece_info
{
   int piece_index;
   int blocks_in_piece;
   int finished;
   int writing;
   int requested;
   block_info* blocks;
};
</pre>
<a name="piece_index"></a><dl class="docutils">
<dt>piece_index</dt>
<dd>the index of the piece in question. <tt class="docutils literal">blocks_in_piece</tt> is the number
of blocks in this particular piece. This number will be the same for
most pieces, but
the last piece may have fewer blocks than the standard pieces.</dd>
</dl>
<a name="blocks_in_piece"></a><dl class="docutils">
<dt>blocks_in_piece</dt>
<dd>the number of blocks in this piece</dd>
</dl>
<a name="finished"></a><dl class="docutils">
<dt>finished</dt>
<dd>the number of blocks that are in the finished state</dd>
</dl>
<a name="writing"></a><dl class="docutils">
<dt>writing</dt>
<dd>the number of blocks that are in the writing state</dd>
</dl>
<a name="requested"></a><dl class="docutils">
<dt>requested</dt>
<dd>the number of blocks that are in the requested state</dd>
</dl>
<a name="blocks"></a><dl class="docutils">
<dt>blocks</dt>
<dd><p class="first">this is an array of <tt class="docutils literal">blocks_in_piece</tt> number of
items. One for each block in the piece.</p>
<div class="admonition warning last">
<p class="first admonition-title">Warning</p>
<p class="last">This is a pointer that points to an array
that's owned by the <a class="reference external" href="reference-Core.html#session">session</a> object. The next time
<a class="reference external" href="reference-Core.html#get_download_queue()">get_download_queue()</a> is called, it will be invalidated.</p>
</div>
</dd>
</dl>
<a name="torrent_handle"></a></div>
<div class="section" id="torrent-handle">
<h2>torrent_handle</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p>
<p>You will usually have to store your torrent handles somewhere, since it's
the object through which you retrieve information about the torrent and
aborts the torrent.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Any member function that returns a value or fills in a value has to be
made synchronously. This means it has to wait for the main thread to
complete the query before it can return. This might potentially be
expensive if done from within a GUI thread that needs to stay
responsive. Try to avoid querying for information you don't need, and
try to do it in as few calls as possible. You can get most of the
interesting information about a torrent from the
<a class="reference external" href="reference-Core.html#status()">torrent_handle::status()</a> call.</p>
</div>
<p>The default constructor will initialize the handle to an invalid state.
Which means you cannot perform any operation on it, unless you first
assign it a valid handle. If you try to perform any operation on an
uninitialized handle, it will throw <tt class="docutils literal">invalid_handle</tt>.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">All operations on a <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> may throw <a class="reference external" href="reference-Error_Codes.html#libtorrent_exception">libtorrent_exception</a>
exception, in case the handle is no longer referring to a torrent.
There is one exception <a class="reference external" href="reference-Storage.html#is_valid()">is_valid()</a> will never throw. Since the torrents
are processed by a background thread, there is no guarantee that a
handle will remain valid between two calls.</p>
</div>
<pre class="literal-block">
struct torrent_handle
{
   <strong>torrent_handle</strong> ();
   <strong>torrent_handle</strong> (torrent_handle const&amp; t);
   torrent_handle&amp; <strong>operator=</strong> (torrent_handle const&amp;) = default;
   void <strong>add_piece</strong> (int piece, char const* data, int flags = 0) const;
   void <strong>read_piece</strong> (int piece) const;
   bool <strong>have_piece</strong> (int piece) const;
   void <strong>get_peer_info</strong> (std::vector&lt;peer_info&gt;&amp; v) const;
   torrent_status <strong>status</strong> (boost::uint32_t flags = 0xffffffff) const;
   void <strong>get_download_queue</strong> (std::vector&lt;partial_piece_info&gt;&amp; queue) const;
   void <strong>reset_piece_deadline</strong> (int index) const;
   void <strong>clear_piece_deadlines</strong> () const;
   void <strong>set_piece_deadline</strong> (int index, int deadline, int flags = 0) const;
   void <strong>set_priority</strong> (int prio) const;
   void <strong>file_progress</strong> (std::vector&lt;boost::int64_t&gt;&amp; progress, int flags = 0) const;
   void <strong>file_status</strong> (std::vector&lt;pool_file_status&gt;&amp; status) const;
   void <strong>clear_error</strong> () const;
   std::vector&lt;announce_entry&gt; <strong>trackers</strong> () const;
   void <strong>replace_trackers</strong> (std::vector&lt;announce_entry&gt; const&amp;) const;
   void <strong>add_tracker</strong> (announce_entry const&amp;) const;
   void <strong>add_url_seed</strong> (std::string const&amp; url) const;
   void <strong>remove_url_seed</strong> (std::string const&amp; url) const;
   std::set&lt;std::string&gt; <strong>url_seeds</strong> () const;
   void <strong>add_http_seed</strong> (std::string const&amp; url) const;
   void <strong>remove_http_seed</strong> (std::string const&amp; url) const;
   std::set&lt;std::string&gt; <strong>http_seeds</strong> () const;
   void <strong>add_extension</strong> (
      boost::function&lt;boost::shared_ptr&lt;torrent_plugin&gt;(torrent_handle const&amp;, void*)&gt; const&amp; ext
      , void* userdata = 0);
   bool <strong>set_metadata</strong> (char const* metadata, int size) const;
   bool <strong>is_valid</strong> () const;
   void <strong>pause</strong> (int flags = 0) const;
   void <strong>resume</strong> () const;
   void <strong>stop_when_ready</strong> (bool b) const;
   void <strong>set_upload_mode</strong> (bool b) const;
   void <strong>set_share_mode</strong> (bool b) const;
   void <strong>flush_cache</strong> () const;
   void <strong>apply_ip_filter</strong> (bool b) const;
   void <strong>force_recheck</strong> () const;
   void <strong>save_resume_data</strong> (int flags = 0) const;
   bool <strong>need_save_resume_data</strong> () const;
   void <strong>auto_managed</strong> (bool m) const;
   void <strong>queue_position_down</strong> () const;
   void <strong>queue_position_top</strong> () const;
   int <strong>queue_position</strong> () const;
   void <strong>queue_position_bottom</strong> () const;
   void <strong>queue_position_up</strong> () const;
   void <strong>queue_position_set</strong> (int p) const;
   void <strong>set_ssl_certificate</strong> (std::string const&amp; certificate
      , std::string const&amp; private_key
      , std::string const&amp; dh_params
      , std::string const&amp; passphrase = &quot;&quot;);
   void <strong>set_ssl_certificate_buffer</strong> (std::string const&amp; certificate
      , std::string const&amp; private_key
      , std::string const&amp; dh_params);
   storage_interface* <strong>get_storage_impl</strong> () const;
   shared_ptr&lt;const torrent_info&gt; <strong>torrent_file</strong> () const;
   void <strong>piece_availability</strong> (std::vector&lt;int&gt;&amp; avail) const;
   int <strong>piece_priority</strong> (int index) const;
   std::vector&lt;int&gt; <strong>piece_priorities</strong> () const;
   void <strong>piece_priority</strong> (int index, int priority) const;
   void <strong>prioritize_pieces</strong> (std::vector&lt;int&gt; const&amp; pieces) const;
   void <strong>prioritize_pieces</strong> (std::vector&lt;std::pair&lt;int, int&gt; &gt; const&amp; pieces) const;
   int <strong>file_priority</strong> (int index) const;
   void <strong>prioritize_files</strong> (std::vector&lt;int&gt; const&amp; files) const;
   void <strong>file_priority</strong> (int index, int priority) const;
   std::vector&lt;int&gt; <strong>file_priorities</strong> () const;
   void <strong>force_reannounce</strong> (int seconds = 0, int tracker_index = -1) const;
   void <strong>force_reannounce</strong> (int seconds, int tracker_index, int flags) const;
   void <strong>force_dht_announce</strong> () const;
   void <strong>scrape_tracker</strong> (int idx = -1) const;
   int <strong>upload_limit</strong> () const;
   int <strong>download_limit</strong> () const;
   void <strong>set_upload_limit</strong> (int limit) const;
   void <strong>set_download_limit</strong> (int limit) const;
   void <strong>set_pinned</strong> (bool p) const;
   void <strong>set_sequential_download</strong> (bool sd) const;
   void <strong>connect_peer</strong> (tcp::endpoint const&amp; adr, int source = 0
      , int flags = 0x1 + 0x4 + 0x8) const;
   int <strong>max_uploads</strong> () const;
   void <strong>set_max_uploads</strong> (int max_uploads) const;
   int <strong>max_connections</strong> () const;
   void <strong>set_max_connections</strong> (int max_connections) const;
   void <strong>move_storage</strong> (std::string const&amp; save_path, int flags = 0) const;
   void <strong>rename_file</strong> (int index, std::string const&amp; new_name) const;
   void <strong>super_seeding</strong> (bool on) const;
   sha1_hash <strong>info_hash</strong> () const;
   bool <strong>operator!=</strong> (const torrent_handle&amp; h) const;
   bool <strong>operator&lt;</strong> (const torrent_handle&amp; h) const;
   bool <strong>operator==</strong> (const torrent_handle&amp; h) const;
   boost::uint32_t <strong>id</strong> () const;
   boost::shared_ptr&lt;torrent&gt; <strong>native_handle</strong> () const;

   enum flags_t
   {
      overwrite_existing,
   };

   enum status_flags_t
   {
      query_distributed_copies,
      query_accurate_download_counters,
      query_last_seen_complete,
      query_pieces,
      query_verified_pieces,
      query_torrent_file,
      query_name,
      query_save_path,
   };

   enum deadline_flags
   {
      alert_when_available,
   };

   enum file_progress_flags_t
   {
      piece_granularity,
   };

   enum pause_flags_t
   {
      graceful_pause,
   };

   enum save_resume_flags_t
   {
      flush_disk_cache,
      save_info_dict,
      only_if_modified,
   };

   enum reannounce_flags_t
   {
      ignore_min_interval,
   };
};
</pre>
<a name="torrent_handle()"></a><div class="section" id="id194">
<h3>torrent_handle()</h3>
<pre class="literal-block">
<strong>torrent_handle</strong> ();
</pre>
<p>constructs a torrent handle that does not refer to a torrent.
i.e. <a class="reference external" href="reference-Storage.html#is_valid()">is_valid()</a> will return false.</p>
<a name="add_piece()"></a></div>
<div class="section" id="add-piece">
<h3>add_piece()</h3>
<pre class="literal-block">
void <strong>add_piece</strong> (int piece, char const* data, int flags = 0) const;
</pre>
<p>This function will write <tt class="docutils literal">data</tt> to the storage as piece <tt class="docutils literal">piece</tt>,
as if it had been downloaded from a peer. <tt class="docutils literal">data</tt> is expected to
point to a buffer of as many bytes as the size of the specified piece.
The data in the buffer is copied and passed on to the disk IO thread
to be written at a later point.</p>
<p>By default, data that's already been downloaded is not overwritten by
this buffer. If you trust this data to be correct (and pass the piece
hash check) you may pass the overwrite_existing flag. This will
instruct libtorrent to overwrite any data that may already have been
downloaded with this data.</p>
<p>Since the data is written asynchronously, you may know that is passed
or failed the hash check by waiting for <a class="reference external" href="reference-Alerts.html#piece_finished_alert">piece_finished_alert</a> or
<a class="reference external" href="reference-Alerts.html#hash_failed_alert">hash_failed_alert</a>.</p>
<a name="read_piece()"></a></div>
<div class="section" id="read-piece">
<h3>read_piece()</h3>
<pre class="literal-block">
void <strong>read_piece</strong> (int piece) const;
</pre>
<p>This function starts an asynchronous read operation of the specified
piece from this torrent. You must have completed the download of the
specified piece before calling this function.</p>
<p>When the read operation is completed, it is passed back through an
<a class="reference external" href="reference-Alerts.html#alert">alert</a>, <a class="reference external" href="reference-Alerts.html#read_piece_alert">read_piece_alert</a>. Since this <a class="reference external" href="reference-Alerts.html#alert">alert</a> is a response to an explicit
call, it will always be posted, regardless of the <a class="reference external" href="reference-Alerts.html#alert">alert</a> mask.</p>
<p>Note that if you read multiple pieces, the read operations are not
guaranteed to finish in the same order as you initiated them.</p>
<a name="have_piece()"></a></div>
<div class="section" id="have-piece">
<h3>have_piece()</h3>
<pre class="literal-block">
bool <strong>have_piece</strong> (int piece) const;
</pre>
<p>Returns true if this piece has been completely downloaded, and false
otherwise.</p>
<a name="get_peer_info()"></a></div>
<div class="section" id="get-peer-info">
<h3>get_peer_info()</h3>
<pre class="literal-block">
void <strong>get_peer_info</strong> (std::vector&lt;peer_info&gt;&amp; v) const;
</pre>
<p>takes a reference to a vector that will be cleared and filled with one
<a class="reference external" href="reference-Bencoding.html#entry">entry</a> for each peer connected to this torrent, given the handle is
valid. If the <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> is invalid, it will throw
<a class="reference external" href="reference-Error_Codes.html#libtorrent_exception">libtorrent_exception</a> exception. Each <a class="reference external" href="reference-Bencoding.html#entry">entry</a> in the vector contains
information about that particular peer. See <a class="reference external" href="reference-Core.html#peer_info">peer_info</a>.</p>
<a name="status()"></a></div>
<div class="section" id="status">
<h3>status()</h3>
<pre class="literal-block">
torrent_status <strong>status</strong> (boost::uint32_t flags = 0xffffffff) const;
</pre>
<p><tt class="docutils literal">status()</tt> will return a structure with information about the status
of this torrent. If the <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> is invalid, it will throw
<a class="reference external" href="reference-Error_Codes.html#libtorrent_exception">libtorrent_exception</a> exception. See <a class="reference external" href="reference-Core.html#torrent_status">torrent_status</a>. The <tt class="docutils literal">flags</tt>
argument filters what information is returned in the <a class="reference external" href="reference-Core.html#torrent_status">torrent_status</a>.
Some information in there is relatively expensive to calculate, and if
you're not interested in it (and see performance issues), you can
filter them out.</p>
<p>By default everything is included. The flags you can use to decide
what to <em>include</em> are defined in the <a class="reference external" href="reference-Core.html#status_flags_t">status_flags_t</a> enum.</p>
<a name="get_download_queue()"></a></div>
<div class="section" id="get-download-queue">
<h3>get_download_queue()</h3>
<pre class="literal-block">
void <strong>get_download_queue</strong> (std::vector&lt;partial_piece_info&gt;&amp; queue) const;
</pre>
<p><tt class="docutils literal">get_download_queue()</tt> takes a non-const reference to a vector which
it will fill with information about pieces that are partially
downloaded or not downloaded at all but partially requested. See
<a class="reference external" href="reference-Core.html#partial_piece_info">partial_piece_info</a> for the fields in the returned vector.</p>
<a name="clear_piece_deadlines()"></a>
<a name="reset_piece_deadline()"></a>
<a name="set_piece_deadline()"></a></div>
<div class="section" id="clear-piece-deadlines-reset-piece-deadline-set-piece-deadline">
<h3>clear_piece_deadlines() reset_piece_deadline() set_piece_deadline()</h3>
<pre class="literal-block">
void <strong>reset_piece_deadline</strong> (int index) const;
void <strong>clear_piece_deadlines</strong> () const;
void <strong>set_piece_deadline</strong> (int index, int deadline, int flags = 0) const;
</pre>
<p>This function sets or resets the deadline associated with a specific
piece index (<tt class="docutils literal">index</tt>). libtorrent will attempt to download this
entire piece before the deadline expires. This is not necessarily
possible, but pieces with a more recent deadline will always be
prioritized over pieces with a deadline further ahead in time. The
deadline (and flags) of a piece can be changed by calling this
function again.</p>
<p>The <tt class="docutils literal">flags</tt> parameter can be used to ask libtorrent to post an <a class="reference external" href="reference-Alerts.html#alert">alert</a>
once the piece has been downloaded, by passing alert_when_available.
When set, the <a class="reference external" href="reference-Alerts.html#read_piece_alert">read_piece_alert</a> <a class="reference external" href="reference-Alerts.html#alert">alert</a> will be delivered, with the piece
data, when it's downloaded.</p>
<p>If the piece is already downloaded when this call is made, nothing
happens, unless the alert_when_available flag is set, in which case it
will have the same effect as calling <a class="reference external" href="reference-Core.html#read_piece()">read_piece()</a> for <tt class="docutils literal">index</tt>.</p>
<p><tt class="docutils literal">deadline</tt> is the number of milliseconds until this piece should be
completed.</p>
<p><tt class="docutils literal">reset_piece_deadline</tt> removes the deadline from the piece. If it
hasn't already been downloaded, it will no longer be considered a
priority.</p>
<p><tt class="docutils literal">clear_piece_deadlines()</tt> removes deadlines on all pieces in
the torrent. As if <a class="reference external" href="reference-Core.html#reset_piece_deadline()">reset_piece_deadline()</a> was called on all pieces.</p>
<a name="set_priority()"></a></div>
<div class="section" id="set-priority">
<h3>set_priority()</h3>
<pre class="literal-block">
void <strong>set_priority</strong> (int prio) const;
</pre>
<p>This sets the bandwidth priority of this torrent. The priority of a
torrent determines how much bandwidth its peers are assigned when
distributing upload and download rate quotas. A high number gives more
bandwidth. The priority must be within the range [0, 255].</p>
<p>The default priority is 0, which is the lowest priority.</p>
<p>To query the priority of a torrent, use the
<tt class="docutils literal"><span class="pre">torrent_handle::status()</span></tt> call.</p>
<p>Torrents with higher priority will not necessarily get as much
bandwidth as they can consume, even if there's is more quota. Other
peers will still be weighed in when bandwidth is being distributed.
With other words, bandwidth is not distributed strictly in order of
priority, but the priority is used as a weight.</p>
<p>Peers whose Torrent has a higher priority will take precedence when
distributing unchoke slots. This is a strict prioritisation where
every interested peer on a high priority torrent will be unchoked
before any other, lower priority, torrents have any peers unchoked.</p>
<a name="file_progress()"></a></div>
<div class="section" id="file-progress">
<h3>file_progress()</h3>
<pre class="literal-block">
void <strong>file_progress</strong> (std::vector&lt;boost::int64_t&gt;&amp; progress, int flags = 0) const;
</pre>
<p>This function fills in the supplied vector with the the number of
bytes downloaded of each file in this torrent. The progress values are
ordered the same as the files in the <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a>. This operation is
not very cheap. Its complexity is <em>O(n + mj)</em>. Where <em>n</em> is the number
of files, <em>m</em> is the number of downloading pieces and <em>j</em> is the
number of blocks in a piece.</p>
<p>The <tt class="docutils literal">flags</tt> parameter can be used to specify the granularity of the
file progress. If left at the default value of 0, the progress will be
as accurate as possible, but also more expensive to calculate. If
<tt class="docutils literal"><span class="pre">torrent_handle::piece_granularity</span></tt> is specified, the progress will
be specified in piece granularity. i.e. only pieces that have been
fully downloaded and passed the hash check count. When specifying
piece granularity, the operation is a lot cheaper, since libtorrent
already keeps track of this internally and no calculation is required.</p>
<a name="file_status()"></a></div>
<div class="section" id="file-status">
<h3>file_status()</h3>
<pre class="literal-block">
void <strong>file_status</strong> (std::vector&lt;pool_file_status&gt;&amp; status) const;
</pre>
<p>This function fills in the passed in vector with status about files
that are open for this torrent. Any file that is not open in this
torrent, will not be reported in the vector, i.e. it's possible that
the vector is empty when returning, if none of the files in the
torrent are currently open.</p>
<p>see pool_file_status.</p>
<a name="clear_error()"></a></div>
<div class="section" id="clear-error">
<h3>clear_error()</h3>
<pre class="literal-block">
void <strong>clear_error</strong> () const;
</pre>
<p>If the torrent is in an error state (i.e. <tt class="docutils literal"><span class="pre">torrent_status::error</span></tt> is
non-empty), this will clear the error and start the torrent again.</p>
<a name="add_tracker()"></a>
<a name="replace_trackers()"></a>
<a name="trackers()"></a></div>
<div class="section" id="add-tracker-replace-trackers-trackers">
<h3>add_tracker() replace_trackers() trackers()</h3>
<pre class="literal-block">
std::vector&lt;announce_entry&gt; <strong>trackers</strong> () const;
void <strong>replace_trackers</strong> (std::vector&lt;announce_entry&gt; const&amp;) const;
void <strong>add_tracker</strong> (announce_entry const&amp;) const;
</pre>
<p><tt class="docutils literal">trackers()</tt> will return the list of trackers for this torrent. The
announce <a class="reference external" href="reference-Bencoding.html#entry">entry</a> contains both a string <tt class="docutils literal">url</tt> which specify the
announce url for the tracker as well as an int <tt class="docutils literal">tier</tt>, which is
specifies the order in which this tracker is tried. If you want
libtorrent to use another list of trackers for this torrent, you can
use <tt class="docutils literal">replace_trackers()</tt> which takes a list of the same form as the
one returned from <tt class="docutils literal">trackers()</tt> and will replace it. If you want an
immediate effect, you have to call <a class="reference external" href="reference-Core.html#force_reannounce()">force_reannounce()</a>. See
<a class="reference external" href="reference-Core.html#announce_entry">announce_entry</a>.</p>
<p><tt class="docutils literal">add_tracker()</tt> will look if the specified tracker is already in the
set. If it is, it doesn't do anything. If it's not in the current set
of trackers, it will insert it in the tier specified in the
<a class="reference external" href="reference-Core.html#announce_entry">announce_entry</a>.</p>
<p>The updated set of trackers will be saved in the resume data, and when
a torrent is started with resume data, the trackers from the resume
data will replace the original ones.</p>
<a name="url_seeds()"></a>
<a name="add_url_seed()"></a>
<a name="remove_url_seed()"></a></div>
<div class="section" id="url-seeds-add-url-seed-remove-url-seed">
<h3>url_seeds() add_url_seed() remove_url_seed()</h3>
<pre class="literal-block">
void <strong>add_url_seed</strong> (std::string const&amp; url) const;
void <strong>remove_url_seed</strong> (std::string const&amp; url) const;
std::set&lt;std::string&gt; <strong>url_seeds</strong> () const;
</pre>
<p><tt class="docutils literal">add_url_seed()</tt> adds another url to the torrent's list of url
seeds. If the given url already exists in that list, the call has no
effect. The torrent will connect to the server and try to download
pieces from it, unless it's paused, queued, checking or seeding.
<tt class="docutils literal">remove_url_seed()</tt> removes the given url if it exists already.
<tt class="docutils literal">url_seeds()</tt> return a set of the url seeds currently in this
torrent. Note that URLs that fails may be removed automatically from
the list.</p>
<p>See <a class="reference external" href="manual-ref.html#http-seeding">http seeding</a> for more information.</p>
<a name="http_seeds()"></a>
<a name="remove_http_seed()"></a>
<a name="add_http_seed()"></a></div>
<div class="section" id="http-seeds-remove-http-seed-add-http-seed">
<h3>http_seeds() remove_http_seed() add_http_seed()</h3>
<pre class="literal-block">
void <strong>add_http_seed</strong> (std::string const&amp; url) const;
void <strong>remove_http_seed</strong> (std::string const&amp; url) const;
std::set&lt;std::string&gt; <strong>http_seeds</strong> () const;
</pre>
<p>These functions are identical as the <tt class="docutils literal">*_url_seed()</tt> variants, but
they operate on <a class="reference external" href="https://bittorrent.org/beps/bep_0017.html">BEP 17</a> web seeds instead of <a class="reference external" href="https://bittorrent.org/beps/bep_0019.html">BEP 19</a>.</p>
<p>See <a class="reference external" href="manual-ref.html#http-seeding">http seeding</a> for more information.</p>
<a name="add_extension()"></a></div>
<div class="section" id="id225">
<h3>add_extension()</h3>
<pre class="literal-block">
void <strong>add_extension</strong> (
      boost::function&lt;boost::shared_ptr&lt;torrent_plugin&gt;(torrent_handle const&amp;, void*)&gt; const&amp; ext
      , void* userdata = 0);
</pre>
<p>add the specified extension to this torrent. The <tt class="docutils literal">ext</tt> argument is
a function that will be called from within libtorrent's context
passing in the internal torrent object and the specified userdata
pointer. The function is expected to return a shared pointer to
a <a class="reference external" href="reference-Plugins.html#torrent_plugin">torrent_plugin</a> instance.</p>
<a name="set_metadata()"></a></div>
<div class="section" id="set-metadata">
<h3>set_metadata()</h3>
<pre class="literal-block">
bool <strong>set_metadata</strong> (char const* metadata, int size) const;
</pre>
<p><tt class="docutils literal">set_metadata</tt> expects the <em>info</em> section of metadata. i.e. The
buffer passed in will be hashed and verified against the info-hash. If
it fails, a <tt class="docutils literal">metadata_failed_alert</tt> will be generated. If it passes,
a <tt class="docutils literal">metadata_received_alert</tt> is generated. The function returns true
if the metadata is successfully set on the torrent, and false
otherwise. If the torrent already has metadata, this function will not
affect the torrent, and false will be returned.</p>
<a name="is_valid()"></a></div>
<div class="section" id="is-valid">
<h3>is_valid()</h3>
<pre class="literal-block">
bool <strong>is_valid</strong> () const;
</pre>
<p>Returns true if this handle refers to a valid torrent and false if it
hasn't been initialized or if the torrent it refers to has been
aborted. Note that a handle may become invalid after it has been added
to the <a class="reference external" href="reference-Core.html#session">session</a>. Usually this is because the storage for the torrent is
somehow invalid or if the filenames are not allowed (and hence cannot
be opened/created) on your filesystem. If such an error occurs, a
<a class="reference external" href="reference-Alerts.html#file_error_alert">file_error_alert</a> is generated and all handles that refers to that
torrent will become invalid.</p>
<a name="pause()"></a>
<a name="resume()"></a></div>
<div class="section" id="pause-resume">
<h3>pause() resume()</h3>
<pre class="literal-block">
void <strong>pause</strong> (int flags = 0) const;
void <strong>resume</strong> () const;
</pre>
<p><tt class="docutils literal">pause()</tt>, and <tt class="docutils literal">resume()</tt> will disconnect all peers and reconnect
all peers respectively. When a torrent is paused, it will however
remember all share ratios to all peers and remember all potential (not
connected) peers. Torrents may be paused automatically if there is a
file error (e.g. disk full) or something similar. See
<a class="reference external" href="reference-Alerts.html#file_error_alert">file_error_alert</a>.</p>
<p>To know if a torrent is paused or not, call
<tt class="docutils literal"><span class="pre">torrent_handle::status()</span></tt> and inspect <tt class="docutils literal"><span class="pre">torrent_status::paused</span></tt>.</p>
<p>The <tt class="docutils literal">flags</tt> argument to pause can be set to
<tt class="docutils literal"><span class="pre">torrent_handle::graceful_pause</span></tt> which will delay the disconnect of
peers that we're still downloading outstanding requests from. The
torrent will not accept any more requests and will disconnect all idle
peers. As soon as a peer is done transferring the blocks that were
requested from it, it is disconnected. This is a graceful shut down of
the torrent in the sense that no downloaded bytes are wasted.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Torrents that are auto-managed may be automatically resumed again. It
does not make sense to pause an auto-managed torrent without making it
not auto-managed first. Torrents are auto-managed by default when added
to the <a class="reference external" href="reference-Core.html#session">session</a>. For more information, see <a class="reference external" href="manual-ref.html#queuing">queuing</a>.</p>
</div>
<a name="stop_when_ready()"></a></div>
<div class="section" id="stop-when-ready">
<h3>stop_when_ready()</h3>
<pre class="literal-block">
void <strong>stop_when_ready</strong> (bool b) const;
</pre>
<p>set or clear the stop-when-ready flag. When this flag is set, the
torrent will <em>force stop</em> whenever it transitions from a
non-data-transferring state into a data-transferring state (referred to
as being ready to download or seed). This is useful for torrents that
should not start downloading or seeding yet, but want to be made ready
to do so. A torrent may need to have its files checked for instance, so
it needs to be started and possibly queued for checking (auto-managed
and started) but as soon as it's done, it should be stopped.</p>
<p><em>Force stopped</em> means auto-managed is set to false and it's paused. As
if auto_manage(false) and <a class="reference external" href="reference-Core.html#pause()">pause()</a> were called on the torrent.</p>
<p>Note that the torrent may transition into a downloading state while
calling this function, and since the logic is edge triggered you may
miss the edge. To avoid this race, if the torrent already is in a
downloading state when this call is made, it will trigger the
stop-when-ready immediately.</p>
<p>When the stop-when-ready logic fires, the flag is cleared. Any
subsequent transitions between downloading and non-downloading states
will not be affected, until this function is used to set it again.</p>
<p>The behavior is more robust when setting this flag as part of adding
the torrent. See <a class="reference external" href="reference-Core.html#add_torrent_params">add_torrent_params</a>.</p>
<p>The stop-when-ready flag fixes the inherent race condition of waiting
for the <a class="reference external" href="reference-Alerts.html#state_changed_alert">state_changed_alert</a> and then call <a class="reference external" href="reference-Core.html#pause()">pause()</a>. The download/seeding
will most likely start in between posting the <a class="reference external" href="reference-Alerts.html#alert">alert</a> and receiving the
call to pause.</p>
<p>A downloading state is one where peers are being connected. Which means
just downloading the metadata via the <tt class="docutils literal">ut_metadata</tt> extension counts
as a downloading state. In order to stop a torrent once the metadata
has been downloaded, instead set all file priorities to dont_download</p>
<a name="set_upload_mode()"></a></div>
<div class="section" id="set-upload-mode">
<h3>set_upload_mode()</h3>
<pre class="literal-block">
void <strong>set_upload_mode</strong> (bool b) const;
</pre>
<p>Explicitly sets the upload mode of the torrent. In upload mode, the
torrent will not request any pieces. If the torrent is auto managed,
it will automatically be taken out of upload mode periodically (see
<tt class="docutils literal"><span class="pre">settings_pack::optimistic_disk_retry</span></tt>). Torrents are
automatically put in upload mode whenever they encounter a disk write
error.</p>
<p><tt class="docutils literal">m</tt> should be true to enter upload mode, and false to leave it.</p>
<p>To test if a torrent is in upload mode, call
<tt class="docutils literal"><span class="pre">torrent_handle::status()</span></tt> and inspect
<tt class="docutils literal"><span class="pre">torrent_status::upload_mode</span></tt>.</p>
<a name="set_share_mode()"></a></div>
<div class="section" id="set-share-mode">
<h3>set_share_mode()</h3>
<pre class="literal-block">
void <strong>set_share_mode</strong> (bool b) const;
</pre>
<p>Enable or disable share mode for this torrent. When in share mode, the
torrent will not necessarily be downloaded, especially not the whole
of it. Only parts that are likely to be distributed to more than 2
other peers are downloaded, and only if the previous prediction was
correct.</p>
<a name="flush_cache()"></a></div>
<div class="section" id="flush-cache">
<h3>flush_cache()</h3>
<pre class="literal-block">
void <strong>flush_cache</strong> () const;
</pre>
<p>Instructs libtorrent to flush all the disk caches for this torrent and
close all file handles. This is done asynchronously and you will be
notified that it's complete through <a class="reference external" href="reference-Alerts.html#cache_flushed_alert">cache_flushed_alert</a>.</p>
<p>Note that by the time you get the <a class="reference external" href="reference-Alerts.html#alert">alert</a>, libtorrent may have cached
more data for the torrent, but you are guaranteed that whatever cached
data libtorrent had by the time you called
<tt class="docutils literal"><span class="pre">torrent_handle::flush_cache()</span></tt> has been written to disk.</p>
<a name="apply_ip_filter()"></a></div>
<div class="section" id="apply-ip-filter">
<h3>apply_ip_filter()</h3>
<pre class="literal-block">
void <strong>apply_ip_filter</strong> (bool b) const;
</pre>
<p>Set to true to apply the <a class="reference external" href="reference-Core.html#session">session</a> global IP filter to this torrent
(which is the default). Set to false to make this torrent ignore the
IP filter.</p>
<a name="force_recheck()"></a></div>
<div class="section" id="force-recheck">
<h3>force_recheck()</h3>
<pre class="literal-block">
void <strong>force_recheck</strong> () const;
</pre>
<p><tt class="docutils literal">force_recheck</tt> puts the torrent back in a state where it assumes to
have no resume data. All peers will be disconnected and the torrent
will stop announcing to the tracker. The torrent will be added to the
checking queue, and will be checked (all the files will be read and
compared to the piece hashes). Once the check is complete, the torrent
will start connecting to peers again, as normal.</p>
<a name="save_resume_data()"></a></div>
<div class="section" id="save-resume-data">
<h3>save_resume_data()</h3>
<pre class="literal-block">
void <strong>save_resume_data</strong> (int flags = 0) const;
</pre>
<p><tt class="docutils literal">save_resume_data()</tt> asks libtorrent to generate fast-resume data for
this torrent.</p>
<p>The <tt class="docutils literal">flags</tt> argument is a bitmask of flags ORed together. see
<a class="reference external" href="reference-Core.html#save_resume_flags_t">save_resume_flags_t</a></p>
<p>This operation is asynchronous, <tt class="docutils literal">save_resume_data</tt> will return
immediately. The resume data is delivered when it's done through an
<a class="reference external" href="reference-Alerts.html#save_resume_data_alert">save_resume_data_alert</a>.</p>
<p>The fast resume data will be empty in the following cases:</p>
<blockquote>
<ol class="arabic simple">
<li>The torrent handle is invalid.</li>
<li>The torrent hasn't received valid metadata and was started without
metadata (see libtorrent's <a class="reference external" href="manual-ref.html#metadata-from-peers">metadata from peers</a> extension)</li>
</ol>
</blockquote>
<p>Note that by the time you receive the fast resume data, it may already
be invalid if the torrent is still downloading! The recommended
practice is to first pause the <a class="reference external" href="reference-Core.html#session">session</a>, then generate the fast resume
data, and then close it down. Make sure to not <a class="reference external" href="reference-Core.html#remove_torrent()">remove_torrent()</a> before
you receive the <a class="reference external" href="reference-Alerts.html#save_resume_data_alert">save_resume_data_alert</a> though. There's no need to
pause when saving intermittent resume data.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">If you pause every torrent individually instead of pausing the
<a class="reference external" href="reference-Core.html#session">session</a>, every torrent will have its paused state saved in the
resume data!</p>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The resume data contains the modification timestamps for all files.
If one file has been modified when the torrent is added again, the
will be rechecked. When shutting down, make sure to flush the disk
cache before saving the resume data. This will make sure that the
file timestamps are up to date and won't be modified after saving
the resume data. The recommended way to do this is to pause the
torrent, which will flush the cache and disconnect all peers.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>It is typically a good idea to save resume data whenever a torrent
is completed or paused. In those cases you don't need to pause the
torrent or the <a class="reference external" href="reference-Core.html#session">session</a>, since the torrent will do no more writing to
its files. If you save resume data for torrents when they are
paused, you can accelerate the shutdown process by not saving resume
data again for paused torrents. Completed torrents should have their
resume data saved when they complete and on exit, since their
statistics might be updated.</p>
<blockquote class="last">
In full allocation mode the resume data is never invalidated by
subsequent writes to the files, since pieces won't move around. This
means that you don't need to pause before writing resume data in full
or sparse mode. If you don't, however, any data written to disk after
you saved resume data and before the <a class="reference external" href="reference-Core.html#session">session</a> closed is lost.</blockquote>
</div>
<p>It also means that if the resume data is out dated, libtorrent will
not re-check the files, but assume that it is fairly recent. The
assumption is that it's better to loose a little bit than to re-check
the entire file.</p>
<p>It is still a good idea to save resume data periodically during
download as well as when closing down.</p>
<p>Example code to pause and save resume data for all torrents and wait
for the alerts:</p>
<pre class="code c++ literal-block">
<span class="keyword">extern</span> <span class="keyword type">int</span> <span class="name">outstanding_resume_data</span><span class="punctuation">;</span> <span class="comment single">// global counter of outstanding resume data
</span><span class="name">std</span><span class="operator">::</span><span class="name">vector</span><span class="operator">&lt;</span><span class="name">torrent_handle</span><span class="operator">&gt;</span> <span class="name">handles</span> <span class="operator">=</span> <span class="name">ses</span><span class="punctuation">.</span><span class="name">get_torrents</span><span class="punctuation">();</span>
<span class="name">ses</span><span class="punctuation">.</span><span class="name">pause</span><span class="punctuation">();</span>
<span class="keyword">for</span> <span class="punctuation">(</span><span class="name">torrent_handle</span> <span class="keyword">const</span><span class="operator">&amp;</span> <span class="name label">h</span> <span class="punctuation">:</span> <span class="name">handles</span><span class="punctuation">)</span>
<span class="punctuation">{</span>
        <span class="keyword">if</span> <span class="punctuation">(</span><span class="operator">!</span><span class="name">h</span><span class="punctuation">.</span><span class="name">is_valid</span><span class="punctuation">())</span> <span class="keyword">continue</span><span class="punctuation">;</span>
        <span class="name">torrent_status</span> <span class="name">s</span> <span class="operator">=</span> <span class="name">h</span><span class="punctuation">.</span><span class="name">status</span><span class="punctuation">();</span>
        <span class="keyword">if</span> <span class="punctuation">(</span><span class="operator">!</span><span class="name">s</span><span class="punctuation">.</span><span class="name">has_metadata</span><span class="punctuation">)</span> <span class="keyword">continue</span><span class="punctuation">;</span>
        <span class="keyword">if</span> <span class="punctuation">(</span><span class="operator">!</span><span class="name">s</span><span class="punctuation">.</span><span class="name">need_save_resume_data</span><span class="punctuation">())</span> <span class="keyword">continue</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="operator">++</span><span class="name">outstanding_resume_data</span><span class="punctuation">;</span>
<span class="punctuation">}</span>

<span class="keyword">while</span> <span class="punctuation">(</span><span class="name">outstanding_resume_data</span> <span class="operator">&gt;</span> <span class="literal number integer">0</span><span class="punctuation">)</span>
<span class="punctuation">{</span>
        <span class="name">alert</span> <span class="keyword">const</span><span class="operator">*</span> <span class="name">a</span> <span class="operator">=</span> <span class="name">ses</span><span class="punctuation">.</span><span class="name">wait_for_alert</span><span class="punctuation">(</span><span class="name">seconds</span><span class="punctuation">(</span><span class="literal number integer">10</span><span class="punctuation">));</span>

        <span class="comment single">// if we don't get an alert within 10 seconds, abort
</span>        <span class="keyword">if</span> <span class="punctuation">(</span><span class="name">a</span> <span class="operator">==</span> <span class="keyword">nullptr</span><span class="punctuation">)</span> <span class="keyword">break</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">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">alert</span><span class="operator">*</span> <span class="name label">i</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="name">alert_cast</span><span class="operator">&lt;</span><span class="name">save_resume_data_failed_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">process_alert</span><span class="punctuation">(</span><span class="name">a</span><span class="punctuation">);</span>
                        <span class="operator">--</span><span class="name">outstanding_resume_data</span><span class="punctuation">;</span>
                        <span class="keyword">continue</span><span class="punctuation">;</span>
                <span class="punctuation">}</span>

                <span class="name">save_resume_data_alert</span> <span class="keyword">const</span><span class="operator">*</span> <span class="name">rd</span> <span class="operator">=</span> <span class="name">alert_cast</span><span class="operator">&lt;</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="keyword">if</span> <span class="punctuation">(</span><span class="name">rd</span> <span class="operator">==</span> <span class="keyword">nullptr</span><span class="punctuation">)</span>
                <span class="punctuation">{</span>
                        <span class="name">process_alert</span><span class="punctuation">(</span><span class="name">a</span><span class="punctuation">);</span>
                        <span class="keyword">continue</span><span class="punctuation">;</span>
                <span class="punctuation">}</span>

                <span class="name">torrent_handle</span> <span class="name">h</span> <span class="operator">=</span> <span class="name">rd</span><span class="operator">-&gt;</span><span class="name">handle</span><span class="punctuation">;</span>
                <span class="name">torrent_status</span> <span class="name">st</span> <span class="operator">=</span> <span class="name">h</span><span class="punctuation">.</span><span class="name">status</span><span class="punctuation">(</span><span class="name">torrent_handle</span><span class="operator">::</span><span class="name">query_save_path</span>
                        <span class="operator">|</span> <span class="name">torrent_handle</span><span class="operator">::</span><span class="name">query_name</span><span class="punctuation">);</span>
                <span class="name">std</span><span class="operator">::</span><span class="name">ofstream</span> <span class="name">out</span><span class="punctuation">((</span><span class="name">st</span><span class="punctuation">.</span><span class="name">save_path</span>
                        <span class="operator">+</span> <span class="literal string">&quot;/&quot;</span> <span class="operator">+</span> <span class="name">st</span><span class="punctuation">.</span><span class="name">name</span> <span class="operator">+</span> <span class="literal string">&quot;.fastresume&quot;</span><span class="punctuation">).</span><span class="name">c_str</span><span class="punctuation">()</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">out</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">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">out</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="operator">--</span><span class="name">outstanding_resume_data</span><span class="punctuation">;</span>
        <span class="punctuation">}</span>
<span class="punctuation">}</span>
</pre>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Note how <tt class="docutils literal">outstanding_resume_data</tt> is a global counter in this
example. This is deliberate, otherwise there is a race condition for
torrents that was just asked to save their resume data, they posted
the <a class="reference external" href="reference-Alerts.html#alert">alert</a>, but it has not been received yet. Those torrents would
report that they don't need to save resume data again, and skipped by
the initial loop, and thwart the counter otherwise.</p>
</div>
<a name="need_save_resume_data()"></a></div>
<div class="section" id="need-save-resume-data">
<h3>need_save_resume_data()</h3>
<pre class="literal-block">
bool <strong>need_save_resume_data</strong> () const;
</pre>
<p>This function returns true if any whole chunk has been downloaded
since the torrent was first loaded or since the last time the resume
data was saved. When saving resume data periodically, it makes sense
to skip any torrent which hasn't downloaded anything since the last
time.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">A torrent's resume data is considered saved as soon as the
<a class="reference external" href="reference-Alerts.html#save_resume_data_alert">save_resume_data_alert</a> is posted. It is important to make sure this
<a class="reference external" href="reference-Alerts.html#alert">alert</a> is received and handled in order for this function to be
meaningful.</p>
</div>
<a name="auto_managed()"></a></div>
<div class="section" id="auto-managed">
<h3>auto_managed()</h3>
<pre class="literal-block">
void <strong>auto_managed</strong> (bool m) const;
</pre>
<p>changes whether the torrent is auto managed or not. For more info,
see <a class="reference external" href="manual-ref.html#queuing">queuing</a>.</p>
<a name="queue_position()"></a>
<a name="queue_position_up()"></a>
<a name="queue_position_bottom()"></a>
<a name="queue_position_down()"></a>
<a name="queue_position_top()"></a></div>
<div class="section" id="queue-position-queue-position-up-queue-position-bottom-queue-position-down-queue-position-top">
<h3>queue_position() queue_position_up() queue_position_bottom() queue_position_down() queue_position_top()</h3>
<pre class="literal-block">
void <strong>queue_position_down</strong> () const;
void <strong>queue_position_top</strong> () const;
int <strong>queue_position</strong> () const;
void <strong>queue_position_bottom</strong> () const;
void <strong>queue_position_up</strong> () const;
</pre>
<p>Every torrent that is added is assigned a queue position exactly one
greater than the greatest queue position of all existing torrents.
Torrents that are being seeded have -1 as their queue position, since
they're no longer in line to be downloaded.</p>
<p>When a torrent is removed or turns into a seed, all torrents with
greater queue positions have their positions decreased to fill in the
space in the sequence.</p>
<p><tt class="docutils literal">queue_position()</tt> returns the torrent's position in the download
queue. The torrents with the smallest numbers are the ones that are
being downloaded. The smaller number, the closer the torrent is to the
front of the line to be started.</p>
<p>The queue position is also available in the <a class="reference external" href="reference-Core.html#torrent_status">torrent_status</a>.</p>
<p>The <tt class="docutils literal"><span class="pre">queue_position_*()</span></tt> functions adjust the torrents position in
the queue. Up means closer to the front and down means closer to the
back of the queue. Top and bottom refers to the front and the back of
the queue respectively.</p>
<a name="queue_position_set()"></a></div>
<div class="section" id="queue-position-set">
<h3>queue_position_set()</h3>
<pre class="literal-block">
void <strong>queue_position_set</strong> (int p) const;
</pre>
<p>updates the position in the queue for this torrent. The relative order
of all other torrents remain intact but their numerical queue position
shifts to make space for this torrent's new position</p>
<a name="set_ssl_certificate_buffer()"></a>
<a name="set_ssl_certificate()"></a></div>
<div class="section" id="set-ssl-certificate-buffer-set-ssl-certificate">
<h3>set_ssl_certificate_buffer() set_ssl_certificate()</h3>
<pre class="literal-block">
void <strong>set_ssl_certificate</strong> (std::string const&amp; certificate
      , std::string const&amp; private_key
      , std::string const&amp; dh_params
      , std::string const&amp; passphrase = &quot;&quot;);
void <strong>set_ssl_certificate_buffer</strong> (std::string const&amp; certificate
      , std::string const&amp; private_key
      , std::string const&amp; dh_params);
</pre>
<p>For SSL torrents, use this to specify a path to a .pem file to use as
this client's certificate. The certificate must be signed by the
certificate in the .torrent file to be valid.</p>
<p>The <a class="reference external" href="reference-Core.html#set_ssl_certificate_buffer()">set_ssl_certificate_buffer()</a> overload takes the actual certificate,
private key and DH params as strings, rather than paths to files. This
overload is only available when libtorrent is built against boost
1.54 or later.</p>
<p><tt class="docutils literal">cert</tt> is a path to the (signed) certificate in .pem format
corresponding to this torrent.</p>
<p><tt class="docutils literal">private_key</tt> is a path to the private key for the specified
certificate. This must be in .pem format.</p>
<p><tt class="docutils literal">dh_params</tt> is a path to the Diffie-Hellman parameter file, which
needs to be in .pem format. You can generate this file using the
openssl command like this: <tt class="docutils literal">openssl dhparam <span class="pre">-outform</span> PEM <span class="pre">-out</span>
dhparams.pem 512</tt>.</p>
<p><tt class="docutils literal">passphrase</tt> may be specified if the private key is encrypted and
requires a passphrase to be decrypted.</p>
<p>Note that when a torrent first starts up, and it needs a certificate,
it will suspend connecting to any peers until it has one. It's
typically desirable to resume the torrent after setting the SSL
certificate.</p>
<p>If you receive a <a class="reference external" href="reference-Alerts.html#torrent_need_cert_alert">torrent_need_cert_alert</a>, you need to call this to
provide a valid cert. If you don't have a cert you won't be allowed to
connect to any peers.</p>
<a name="get_storage_impl()"></a></div>
<div class="section" id="get-storage-impl">
<h3>get_storage_impl()</h3>
<pre class="literal-block">
storage_interface* <strong>get_storage_impl</strong> () const;
</pre>
<p>Returns the storage implementation for this torrent. This depends on the
storage constructor function that was passed to add_torrent.</p>
<a name="torrent_file()"></a></div>
<div class="section" id="torrent-file">
<h3>torrent_file()</h3>
<pre class="literal-block">
shared_ptr&lt;const torrent_info&gt; <strong>torrent_file</strong> () const;
</pre>
<p>Returns a pointer to the <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object associated with this
torrent. The <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object may be a copy of the internal object.
If the torrent doesn't have metadata, the pointer will not be
initialized (i.e. a NULL pointer). The torrent may be in a state
without metadata only if it was started without a .torrent file, e.g.
by using the libtorrent extension of just supplying a tracker and
info-hash.</p>
<a name="piece_availability()"></a></div>
<div class="section" id="piece-availability">
<h3>piece_availability()</h3>
<pre class="literal-block">
void <strong>piece_availability</strong> (std::vector&lt;int&gt;&amp; avail) const;
</pre>
<p>Fills the specified <tt class="docutils literal"><span class="pre">std::vector&lt;int&gt;</span></tt> with the availability for
each piece in this torrent. libtorrent does not keep track of
availability for seeds, so if the torrent is seeding the availability
for all pieces is reported as 0.</p>
<p>The piece availability is the number of peers that we are connected
that has advertised having a particular piece. This is the information
that libtorrent uses in order to prefer picking rare pieces.</p>
<a name="piece_priority()"></a>
<a name="prioritize_pieces()"></a>
<a name="piece_priorities()"></a></div>
<div class="section" id="piece-priority-prioritize-pieces-piece-priorities">
<h3>piece_priority() prioritize_pieces() piece_priorities()</h3>
<pre class="literal-block">
int <strong>piece_priority</strong> (int index) const;
std::vector&lt;int&gt; <strong>piece_priorities</strong> () const;
void <strong>piece_priority</strong> (int index, int priority) const;
void <strong>prioritize_pieces</strong> (std::vector&lt;int&gt; const&amp; pieces) const;
void <strong>prioritize_pieces</strong> (std::vector&lt;std::pair&lt;int, int&gt; &gt; const&amp; pieces) const;
</pre>
<p>These functions are used to set and get the priority of individual
pieces. By default all pieces have priority 4. That means that the
random rarest first algorithm is effectively active for all pieces.
You may however change the priority of individual pieces. There are 8
priority levels. 0 means not to download the piece at all. Otherwise,
lower priority values means less likely to be picked. Piece priority
takes precedence over piece availability. Every piece with priority 7
will be attempted to be picked before a priority 6 piece and so on.</p>
<p>The default priority of pieces is 4.</p>
<p>Piece priorities can not be changed for torrents that have not
downloaded the metadata yet. Magnet links won't have metadata
immediately. see the <a class="reference external" href="reference-Alerts.html#metadata_received_alert">metadata_received_alert</a>.</p>
<p><tt class="docutils literal">piece_priority</tt> sets or gets the priority for an individual piece,
specified by <tt class="docutils literal">index</tt>.</p>
<p><tt class="docutils literal">prioritize_pieces</tt> takes a vector of integers, one integer per
piece in the torrent. All the piece priorities will be updated with
the priorities in the vector.
The second overload of <tt class="docutils literal">prioritize_pieces</tt> that takes a vector of pairs
will update the priorities of only select pieces, and leave all other
unaffected. Each pair is (piece, priority). That is, the first item is
the piece index and the second item is the priority of that piece.
Invalid entries, where the piece index or priority is out of range, are
not allowed.</p>
<p><tt class="docutils literal">piece_priorities</tt> returns a vector with one element for each piece
in the torrent. Each element is the current priority of that piece.</p>
<p>It's possible to cancel the effect of <em>file</em> priorities by setting the
priorities for the affected pieces. Care has to be taken when mixing
usage of file- and piece priorities.</p>
<a name="file_priorities()"></a>
<a name="prioritize_files()"></a>
<a name="file_priority()"></a></div>
<div class="section" id="file-priorities-prioritize-files-file-priority">
<h3>file_priorities() prioritize_files() file_priority()</h3>
<pre class="literal-block">
int <strong>file_priority</strong> (int index) const;
void <strong>prioritize_files</strong> (std::vector&lt;int&gt; const&amp; files) const;
void <strong>file_priority</strong> (int index, int priority) const;
std::vector&lt;int&gt; <strong>file_priorities</strong> () const;
</pre>
<p><tt class="docutils literal">index</tt> must be in the range [0, number_of_files).</p>
<p><tt class="docutils literal">file_priority()</tt> queries or sets the priority of file <tt class="docutils literal">index</tt>.</p>
<p><tt class="docutils literal">prioritize_files()</tt> takes a vector that has at as many elements as
there are files in the torrent. Each <a class="reference external" href="reference-Bencoding.html#entry">entry</a> is the priority of that
file. The function sets the priorities of all the pieces in the
torrent based on the vector.</p>
<p><tt class="docutils literal">file_priorities()</tt> returns a vector with the priorities of all
files.</p>
<p>The priority values are the same as for <a class="reference external" href="reference-Core.html#piece_priority()">piece_priority()</a>.</p>
<p>Whenever a file priority is changed, all other piece priorities are
reset to match the file priorities. In order to maintain special
priorities for particular pieces, <a class="reference external" href="reference-Core.html#piece_priority()">piece_priority()</a> has to be called
again for those pieces.</p>
<p>You cannot set the file priorities on a torrent that does not yet have
metadata or a torrent that is a seed. <tt class="docutils literal">file_priority(int, int)</tt> and
<a class="reference external" href="reference-Core.html#prioritize_files()">prioritize_files()</a> are both no-ops for such torrents.</p>
<p>Since changing file priorities may involve disk operations (of moving
files in- and out of the part file), the internal accounting of file
priorities happen asynchronously. i.e. setting file priorities and then
immediately querying them may not yield the same priorities just set.
However, the <em>piece</em> priorities are updated immediately.</p>
<p>when combining file- and piece priorities, the resume file will record
both. When loading the resume data, the file priorities will be applied
first, then the piece priorities.</p>
<a name="force_reannounce()"></a>
<a name="force_dht_announce()"></a></div>
<div class="section" id="force-reannounce-force-dht-announce">
<h3>force_reannounce() force_dht_announce()</h3>
<pre class="literal-block">
void <strong>force_reannounce</strong> (int seconds = 0, int tracker_index = -1) const;
void <strong>force_reannounce</strong> (int seconds, int tracker_index, int flags) const;
void <strong>force_dht_announce</strong> () const;
</pre>
<p><tt class="docutils literal">force_reannounce()</tt> will force this torrent to do another tracker
request, to receive new peers. The <tt class="docutils literal">seconds</tt> argument specifies how
many seconds from now to issue the tracker announces.</p>
<p>If the tracker's <tt class="docutils literal">min_interval</tt> has not passed since the last
announce, the forced announce will be scheduled to happen immediately
as the <tt class="docutils literal">min_interval</tt> expires. This is to honor trackers minimum
re-announce interval settings.</p>
<p>The <tt class="docutils literal">tracker_index</tt> argument specifies which tracker to re-announce.
If set to -1 (which is the default), all trackers are re-announce.</p>
<p>The <tt class="docutils literal">flags</tt> argument can be used to affect the re-announce. See
<a class="reference external" href="reference-Core.html#reannounce_flags_t">reannounce_flags_t</a>.</p>
<p><tt class="docutils literal">force_dht_announce</tt> will announce the torrent to the DHT
immediately.</p>
<a name="scrape_tracker()"></a></div>
<div class="section" id="scrape-tracker">
<h3>scrape_tracker()</h3>
<pre class="literal-block">
void <strong>scrape_tracker</strong> (int idx = -1) const;
</pre>
<p><tt class="docutils literal">scrape_tracker()</tt> will send a scrape request to a tracker. By
default (<tt class="docutils literal">idx</tt> = -1) it will scrape the last working tracker. If
<tt class="docutils literal">idx</tt> is &gt;= 0, the tracker with the specified index will scraped.</p>
<p>A scrape request queries the tracker for statistics such as total
number of incomplete peers, complete peers, number of downloads etc.</p>
<p>This request will specifically update the <tt class="docutils literal">num_complete</tt> and
<tt class="docutils literal">num_incomplete</tt> fields in the <a class="reference external" href="reference-Core.html#torrent_status">torrent_status</a> struct once it
completes. When it completes, it will generate a <a class="reference external" href="reference-Alerts.html#scrape_reply_alert">scrape_reply_alert</a>.
If it fails, it will generate a <a class="reference external" href="reference-Alerts.html#scrape_failed_alert">scrape_failed_alert</a>.</p>
<a name="set_upload_limit()"></a>
<a name="upload_limit()"></a>
<a name="download_limit()"></a>
<a name="set_download_limit()"></a></div>
<div class="section" id="set-upload-limit-upload-limit-download-limit-set-download-limit">
<h3>set_upload_limit() upload_limit() download_limit() set_download_limit()</h3>
<pre class="literal-block">
int <strong>upload_limit</strong> () const;
int <strong>download_limit</strong> () const;
void <strong>set_upload_limit</strong> (int limit) const;
void <strong>set_download_limit</strong> (int limit) const;
</pre>
<p><tt class="docutils literal">set_upload_limit</tt> will limit the upload bandwidth used by this
particular torrent to the limit you set. It is given as the number of
bytes per second the torrent is allowed to upload.
<tt class="docutils literal">set_download_limit</tt> works the same way but for download bandwidth
instead of upload bandwidth. Note that setting a higher limit on a
torrent then the global limit
(<tt class="docutils literal"><span class="pre">settings_pack::upload_rate_limit</span></tt>) will not override the global
rate limit. The torrent can never upload more than the global rate
limit.</p>
<p><tt class="docutils literal">upload_limit</tt> and <tt class="docutils literal">download_limit</tt> will return the current limit
setting, for upload and download, respectively.</p>
<p>Local peers are not rate limited by default. see <a class="reference external" href="manual-ref.html#peer-classes">peer classes</a>.</p>
<a name="set_pinned()"></a></div>
<div class="section" id="set-pinned">
<h3>set_pinned()</h3>
<pre class="literal-block">
void <strong>set_pinned</strong> (bool p) const;
</pre>
<p>A pinned torrent may not be unloaded by libtorrent. When the dynamic
loading and unloading of torrents is enabled (by setting a load
function on the <a class="reference external" href="reference-Core.html#session">session</a>), this can be used to exempt certain torrents
from the unloading logic.</p>
<p>Magnet links, and other torrents that start out without having
metadata are pinned automatically. This is to give the client a chance
to get the metadata and save it before it's unloaded. In this case, it
may be useful to unpin the torrent once its metadata has been saved
to disk.</p>
<p>For more information about dynamically loading and unloading torrents,
see <a class="reference external" href="manual-ref.html#dynamic-loading-of-torrent-files">dynamic loading of torrent files</a>.</p>
<a name="set_sequential_download()"></a></div>
<div class="section" id="set-sequential-download">
<h3>set_sequential_download()</h3>
<pre class="literal-block">
void <strong>set_sequential_download</strong> (bool sd) const;
</pre>
<p><tt class="docutils literal">set_sequential_download()</tt> enables or disables <em>sequential
download</em>. When enabled, the piece picker will pick pieces in sequence
instead of rarest first. In this mode, piece priorities are ignored,
with the exception of priority 7, which are still preferred over the
sequential piece order.</p>
<p>Enabling sequential download will affect the piece distribution
negatively in the swarm. It should be used sparingly.</p>
<a name="connect_peer()"></a></div>
<div class="section" id="connect-peer">
<h3>connect_peer()</h3>
<pre class="literal-block">
void <strong>connect_peer</strong> (tcp::endpoint const&amp; adr, int source = 0
      , int flags = 0x1 + 0x4 + 0x8) const;
</pre>
<p><tt class="docutils literal">connect_peer()</tt> is a way to manually connect to peers that one
believe is a part of the torrent. If the peer does not respond, or is
not a member of this torrent, it will simply be disconnected. No harm
can be done by using this other than an unnecessary connection attempt
is made. If the torrent is uninitialized or in queued or checking
mode, this will throw <a class="reference external" href="reference-Error_Codes.html#libtorrent_exception">libtorrent_exception</a>. The second (optional)
argument will be bitwise ORed into the source mask of this peer.
Typically this is one of the source flags in <a class="reference external" href="reference-Core.html#peer_info">peer_info</a>. i.e.
<tt class="docutils literal">tracker</tt>, <tt class="docutils literal">pex</tt>, <tt class="docutils literal">dht</tt> etc.</p>
<p><tt class="docutils literal">flags</tt> are the same flags that are passed along with the <tt class="docutils literal">ut_pex</tt> extension.</p>
<table border="1" class="docutils">
<colgroup>
<col width="6%" />
<col width="94%" />
</colgroup>
<tbody valign="top">
<tr><td>0x01</td>
<td>peer supports encryption.</td>
</tr>
<tr><td>0x02</td>
<td>peer is a seed</td>
</tr>
<tr><td>0x04</td>
<td>supports uTP. If this is not set, the peer will only be contacted
over TCP.</td>
</tr>
<tr><td>0x08</td>
<td>supports hole punching protocol. If this
flag is received from a peer, it can be
used as a rendezvous point in case direct
connections to the peer fail</td>
</tr>
</tbody>
</table>
<a name="max_uploads()"></a>
<a name="set_max_uploads()"></a></div>
<div class="section" id="max-uploads-set-max-uploads">
<h3>max_uploads() set_max_uploads()</h3>
<pre class="literal-block">
int <strong>max_uploads</strong> () const;
void <strong>set_max_uploads</strong> (int max_uploads) const;
</pre>
<p><tt class="docutils literal">set_max_uploads()</tt> sets the maximum number of peers that's unchoked
at the same time on this torrent. If you set this to -1, there will be
no limit. This defaults to infinite. The primary setting controlling
this is the global unchoke slots limit, set by unchoke_slots_limit in
<a class="reference external" href="reference-Settings.html#settings_pack">settings_pack</a>.</p>
<p><tt class="docutils literal">max_uploads()</tt> returns the current settings.</p>
<a name="max_connections()"></a>
<a name="set_max_connections()"></a></div>
<div class="section" id="max-connections-set-max-connections">
<h3>max_connections() set_max_connections()</h3>
<pre class="literal-block">
int <strong>max_connections</strong> () const;
void <strong>set_max_connections</strong> (int max_connections) const;
</pre>
<p><tt class="docutils literal">set_max_connections()</tt> sets the maximum number of connection this
torrent will open. If all connections are used up, incoming
connections may be refused or poor connections may be closed. This
must be at least 2. The default is unlimited number of connections. If
-1 is given to the function, it means unlimited. There is also a
global limit of the number of connections, set by
<tt class="docutils literal">connections_limit</tt> in <a class="reference external" href="reference-Settings.html#settings_pack">settings_pack</a>.</p>
<p><tt class="docutils literal">max_connections()</tt> returns the current settings.</p>
<a name="move_storage()"></a></div>
<div class="section" id="move-storage">
<h3>move_storage()</h3>
<pre class="literal-block">
void <strong>move_storage</strong> (std::string const&amp; save_path, int flags = 0) const;
</pre>
<p>Moves the file(s) that this torrent are currently seeding from or
downloading to. If the given <tt class="docutils literal">save_path</tt> is not located on the same
drive as the original save path, the files will be copied to the new
drive and removed from their original location. This will block all
other disk IO, and other torrents download and upload rates may drop
while copying the file.</p>
<p>Since disk IO is performed in a separate thread, this operation is
also asynchronous. Once the operation completes, the
<tt class="docutils literal">storage_moved_alert</tt> is generated, with the new path as the
message. If the move fails for some reason,
<tt class="docutils literal">storage_moved_failed_alert</tt> is generated instead, containing the
error message.</p>
<p>The <tt class="docutils literal">flags</tt> argument determines the behavior of the copying/moving
of the files in the torrent. see <a class="reference external" href="reference-Custom_Storage.html#move_flags_t">move_flags_t</a>.</p>
<blockquote>
<ul class="simple">
<li>always_replace_files = 0</li>
<li>fail_if_exist = 1</li>
<li>dont_replace = 2</li>
</ul>
</blockquote>
<p><tt class="docutils literal">always_replace_files</tt> is the default and replaces any file that
exist in both the source directory and the target directory.</p>
<p><tt class="docutils literal">fail_if_exist</tt> first check to see that none of the copy operations
would cause an overwrite. If it would, it will fail. Otherwise it will
proceed as if it was in <tt class="docutils literal">always_replace_files</tt> mode. Note that there
is an inherent race condition here. If the files in the target
directory appear after the check but before the copy or move
completes, they will be overwritten. When failing because of files
already existing in the target path, the <tt class="docutils literal">error</tt> of
<tt class="docutils literal">move_storage_failed_alert</tt> is set to
<tt class="docutils literal"><span class="pre">boost::system::errc::file_exists</span></tt>.</p>
<p>The intention is that a client may use this as a probe, and if it
fails, ask the user which mode to use. The client may then re-issue
the <tt class="docutils literal">move_storage</tt> call with one of the other modes.</p>
<p><tt class="docutils literal">dont_replace</tt> always keeps the existing file in the target
directory, if there is one. The source files will still be removed in
that case. Note that it won't automatically re-check files. If an
incomplete torrent is moved into a directory with the complete files,
pause, move, force-recheck and resume. Without the re-checking, the
torrent will keep downloading and files in the new download directory
will be overwritten.</p>
<p>Files that have been renamed to have absolute paths are not moved by
this function. Keep in mind that files that don't belong to the
torrent but are stored in the torrent's directory may be moved as
well. This goes for files that have been renamed to absolute paths
that still end up inside the save path.</p>
<a name="rename_file()"></a></div>
<div class="section" id="rename-file">
<h3>rename_file()</h3>
<pre class="literal-block">
void <strong>rename_file</strong> (int index, std::string const&amp; new_name) const;
</pre>
<p>Renames the file with the given index asynchronously. The rename
operation is complete when either a <a class="reference external" href="reference-Alerts.html#file_renamed_alert">file_renamed_alert</a> or
<a class="reference external" href="reference-Alerts.html#file_rename_failed_alert">file_rename_failed_alert</a> is posted.</p>
<a name="super_seeding()"></a></div>
<div class="section" id="super-seeding">
<h3>super_seeding()</h3>
<pre class="literal-block">
void <strong>super_seeding</strong> (bool on) const;
</pre>
<p>Enables or disabled super seeding/initial seeding for this torrent.
The torrent needs to be a seed for this to take effect.</p>
<a name="info_hash()"></a></div>
<div class="section" id="info-hash">
<h3>info_hash()</h3>
<pre class="literal-block">
sha1_hash <strong>info_hash</strong> () const;
</pre>
<p><tt class="docutils literal">info_hash()</tt> returns the info-hash of the torrent. If this handle
is to a torrent that hasn't loaded yet (for instance by being added)
by a URL, the returned value is undefined.</p>
<a name="operator!=()"></a>
<a name="operator<()"></a>
<a name="operator==()"></a></div>
<div class="section" id="operator-operator-operator">
<h3>operator!=() operator&lt;() operator==()</h3>
<pre class="literal-block">
bool <strong>operator!=</strong> (const torrent_handle&amp; h) const;
bool <strong>operator&lt;</strong> (const torrent_handle&amp; h) const;
bool <strong>operator==</strong> (const torrent_handle&amp; h) const;
</pre>
<p>comparison operators. The order of the torrents is unspecified
but stable.</p>
<a name="native_handle()"></a></div>
<div class="section" id="id277">
<h3>native_handle()</h3>
<pre class="literal-block">
boost::shared_ptr&lt;torrent&gt; <strong>native_handle</strong> () const;
</pre>
<p>This function is intended only for use by plugins and the <a class="reference external" href="reference-Alerts.html#alert">alert</a>
dispatch function. This type does not have a stable API and should
be relied on as little as possible.</p>
<a name="flags_t"></a></div>
<div class="section" id="enum-flags-t">
<h3>enum flags_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="50%" />
<col width="18%" />
<col width="33%" />
</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>overwrite_existing</td>
<td>1</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<a name="status_flags_t"></a></div>
<div class="section" id="enum-status-flags-t">
<h3>enum status_flags_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="31%" />
<col width="6%" />
<col width="63%" />
</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>query_distributed_copies</td>
<td>1</td>
<td>calculates <tt class="docutils literal">distributed_copies</tt>, <tt class="docutils literal">distributed_full_copies</tt> and
<tt class="docutils literal">distributed_fraction</tt>.</td>
</tr>
<tr><td>query_accurate_download_counters</td>
<td>2</td>
<td>includes partial downloaded blocks in <tt class="docutils literal">total_done</tt> and
<tt class="docutils literal">total_wanted_done</tt>.</td>
</tr>
<tr><td>query_last_seen_complete</td>
<td>4</td>
<td>includes <tt class="docutils literal">last_seen_complete</tt>.</td>
</tr>
<tr><td>query_pieces</td>
<td>8</td>
<td>includes <tt class="docutils literal">pieces</tt>.</td>
</tr>
<tr><td>query_verified_pieces</td>
<td>16</td>
<td>includes <tt class="docutils literal">verified_pieces</tt> (only applies to torrents in <em>seed
mode</em>).</td>
</tr>
<tr><td>query_torrent_file</td>
<td>32</td>
<td>includes <tt class="docutils literal">torrent_file</tt>, which is all the static information from
the .torrent file.</td>
</tr>
<tr><td>query_name</td>
<td>64</td>
<td>includes <tt class="docutils literal">name</tt>, the name of the torrent. This is either derived
from the .torrent file, or from the <tt class="docutils literal">&amp;dn=</tt> magnet link argument
or possibly some other source. If the name of the torrent is not
known, this is an empty string.</td>
</tr>
<tr><td>query_save_path</td>
<td>128</td>
<td>includes <tt class="docutils literal">save_path</tt>, the path to the directory the files of the
torrent are saved to.</td>
</tr>
</tbody>
</table>
<a name="deadline_flags"></a></div>
<div class="section" id="enum-deadline-flags">
<h3>enum deadline_flags</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="52%" />
<col width="17%" />
<col width="31%" />
</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>alert_when_available</td>
<td>1</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<a name="file_progress_flags_t"></a></div>
<div class="section" id="enum-file-progress-flags-t">
<h3>enum file_progress_flags_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="7%" />
<col width="73%" />
</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>piece_granularity</td>
<td>1</td>
<td>only calculate file progress at piece granularity. This makes
the <a class="reference external" href="reference-Core.html#file_progress()">file_progress()</a> call cheaper and also only takes bytes that
have passed the hash check into account, so progress cannot
regress in this mode.</td>
</tr>
</tbody>
</table>
<a name="pause_flags_t"></a></div>
<div class="section" id="enum-pause-flags-t">
<h3>enum pause_flags_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="44%" />
<col width="19%" />
<col width="36%" />
</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>graceful_pause</td>
<td>1</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<a name="save_resume_flags_t"></a></div>
<div class="section" id="enum-save-resume-flags-t">
<h3>enum save_resume_flags_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="19%" />
<col width="7%" />
<col width="74%" />
</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>flush_disk_cache</td>
<td>1</td>
<td>the disk cache will be flushed before creating the resume data.
This avoids a problem with file timestamps in the resume data in
case the cache hasn't been flushed yet.</td>
</tr>
<tr><td>save_info_dict</td>
<td>2</td>
<td>the resume data will contain the metadata from the torrent file as
well. This is default for any torrent that's added without a
torrent file (such as a magnet link or a URL).</td>
</tr>
<tr><td>only_if_modified</td>
<td>4</td>
<td>if nothing significant has changed in the torrent since the last
time resume data was saved, fail this attempt. Significant changes
primarily include more data having been downloaded, file or piece
priorities having changed etc. If the resume data doesn't need
saving, a <a class="reference external" href="reference-Alerts.html#save_resume_data_failed_alert">save_resume_data_failed_alert</a> is posted with the error
resume_data_not_modified.</td>
</tr>
</tbody>
</table>
<a name="reannounce_flags_t"></a></div>
<div class="section" id="enum-reannounce-flags-t">
<h3>enum reannounce_flags_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="22%" />
<col width="7%" />
<col width="71%" />
</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>ignore_min_interval</td>
<td>1</td>
<td>by default, force-reannounce will still honor the min-interval
published by the tracker. If this flag is set, it will be ignored
and the tracker is announced immediately.</td>
</tr>
</tbody>
</table>
<a name="cache_status"></a></div>
</div>
<div class="section" id="cache-status">
<h2>cache_status</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/disk_io_thread.hpp">libtorrent/disk_io_thread.hpp</a>&quot;</p>
<p>this struct holds a number of statistics counters
relevant for the disk io thread and disk cache.</p>
<pre class="literal-block">
struct cache_status
{
   <strong>cache_status</strong> ();

   std::vector&lt;cached_piece_info&gt; pieces;
};
</pre>
<a name="cache_status()"></a><div class="section" id="id289">
<h3>cache_status()</h3>
<pre class="literal-block">
<strong>cache_status</strong> ();
</pre>
<p>initializes all counters to 0</p>
<a name="web_seed_entry"></a></div>
</div>
<div class="section" id="web-seed-entry">
<h2>web_seed_entry</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_info.hpp">libtorrent/torrent_info.hpp</a>&quot;</p>
<p>the <a class="reference external" href="reference-Core.html#web_seed_entry">web_seed_entry</a> holds information about a web seed (also known
as URL seed or HTTP seed). It is essentially a URL with some state
associated with it. For more information, see <a class="reference external" href="https://bittorrent.org/beps/bep_0017.html">BEP 17</a> and <a class="reference external" href="https://bittorrent.org/beps/bep_0019.html">BEP 19</a>.</p>
<pre class="literal-block">
struct web_seed_entry
{
   <strong>web_seed_entry</strong> (std::string const&amp; url_, type_t type_
      , std::string const&amp; auth_ = std::string()
      , headers_t const&amp; extra_headers_ = headers_t());
   bool <strong>operator==</strong> (web_seed_entry const&amp; e) const;
   bool <strong>operator&lt;</strong> (web_seed_entry const&amp; e) const;

   enum type_t
   {
      url_seed,
      http_seed,
   };

   std::string url;
   std::string auth;
   headers_t extra_headers;
   boost::uint8_t type;
};
</pre>
<a name="operator==()"></a><div class="section" id="id292">
<h3>operator==()</h3>
<pre class="literal-block">
bool <strong>operator==</strong> (web_seed_entry const&amp; e) const;
</pre>
<p>URL and type comparison</p>
<a name="operator<()"></a></div>
<div class="section" id="id293">
<h3>operator&lt;()</h3>
<pre class="literal-block">
bool <strong>operator&lt;</strong> (web_seed_entry const&amp; e) const;
</pre>
<p>URL and type less-than comparison</p>
<a name="type_t"></a></div>
<div class="section" id="enum-type-t">
<h3>enum type_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_info.hpp">libtorrent/torrent_info.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="35%" />
<col width="23%" />
<col width="42%" />
</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>url_seed</td>
<td>0</td>
<td>&nbsp;</td>
</tr>
<tr><td>http_seed</td>
<td>1</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<a name="url"></a><dl class="docutils">
<dt>url</dt>
<dd>The URL of the web seed</dd>
</dl>
<a name="auth"></a><dl class="docutils">
<dt>auth</dt>
<dd>Optional authentication. If this is set, it's passed
in as HTTP basic auth to the web seed. The format is:
username:password.</dd>
</dl>
<a name="extra_headers"></a><dl class="docutils">
<dt>extra_headers</dt>
<dd>Any extra HTTP headers that need to be passed to the web seed</dd>
</dl>
<a name="type"></a><dl class="docutils">
<dt>type</dt>
<dd>The type of web seed (see <a class="reference external" href="reference-Core.html#type_t">type_t</a>)</dd>
</dl>
<a name="torrent_info"></a></div>
</div>
<div class="section" id="torrent-info">
<h2>torrent_info</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_info.hpp">libtorrent/torrent_info.hpp</a>&quot;</p>
<p>TODO: there may be some opportunities to optimize the size if <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a>.
specifically to turn some std::string and std::vector into pointers</p>
<pre class="literal-block">
class torrent_info
{
   <strong>torrent_info</strong> (std::string const&amp; filename, int flags = 0);
   <strong>torrent_info</strong> (std::string const&amp; filename, error_code&amp; ec, int flags = 0);
   <strong>torrent_info</strong> (char const* buffer, int size, error_code&amp; ec, int flags = 0);
   <strong>torrent_info</strong> (sha1_hash const&amp; info_hash, int flags = 0);
   <strong>torrent_info</strong> (bdecode_node const&amp; torrent_file, error_code&amp; ec, int flags = 0);
   <strong>torrent_info</strong> (char const* buffer, int size, int flags = 0);
   <strong>torrent_info</strong> (bdecode_node const&amp; torrent_file, int flags = 0);
   <strong>torrent_info</strong> (torrent_info const&amp; t);
   <strong>~torrent_info</strong> ();
   file_storage const&amp; <strong>files</strong> () const;
   file_storage const&amp; <strong>orig_files</strong> () const;
   void <strong>rename_file</strong> (int index, std::string const&amp; new_filename);
   void <strong>remap_files</strong> (file_storage const&amp; f);
   std::vector&lt;announce_entry&gt; const&amp; <strong>trackers</strong> () const;
   void <strong>add_tracker</strong> (std::string const&amp; url, int tier = 0);
   std::vector&lt;sha1_hash&gt; <strong>similar_torrents</strong> () const;
   std::vector&lt;std::string&gt; <strong>collections</strong> () const;
   void <strong>add_url_seed</strong> (std::string const&amp; url
      , std::string const&amp; extern_auth = std::string()
      , web_seed_entry::headers_t const&amp; extra_headers = web_seed_entry::headers_t());
   std::vector&lt;web_seed_entry&gt; const&amp; <strong>web_seeds</strong> () const;
   void <strong>set_web_seeds</strong> (std::vector&lt;web_seed_entry&gt; seeds);
   void <strong>add_http_seed</strong> (std::string const&amp; url
      , std::string const&amp; extern_auth = std::string()
      , web_seed_entry::headers_t const&amp; extra_headers = web_seed_entry::headers_t());
   boost::int64_t <strong>total_size</strong> () const;
   int <strong>num_pieces</strong> () const;
   int <strong>piece_length</strong> () const;
   const sha1_hash&amp; <strong>info_hash</strong> () const;
   int <strong>num_files</strong> () const;
   std::vector&lt;file_slice&gt; <strong>map_block</strong> (int piece, boost::int64_t offset, int size) const;
   peer_request <strong>map_file</strong> (int file, boost::int64_t offset, int size) const;
   void <strong>unload</strong> ();
   void <strong>load</strong> (char const* buffer, int size, error_code&amp; ec);
   std::string <strong>ssl_cert</strong> () const;
   bool <strong>is_valid</strong> () const;
   bool <strong>priv</strong> () const;
   bool <strong>is_i2p</strong> () const;
   sha1_hash <strong>hash_for_piece</strong> (int index) const;
   char const* <strong>hash_for_piece_ptr</strong> (int index) const;
   int <strong>piece_size</strong> (int index) const;
   bool <strong>is_loaded</strong> () const;
   std::vector&lt;sha1_hash&gt; const&amp; <strong>merkle_tree</strong> () const;
   void <strong>set_merkle_tree</strong> (std::vector&lt;sha1_hash&gt;&amp; h);
   boost::optional&lt;time_t&gt; <strong>creation_date</strong> () const;
   const std::string&amp; <strong>name</strong> () const;
   const std::string&amp; <strong>comment</strong> () const;
   const std::string&amp; <strong>creator</strong> () const;
   nodes_t const&amp; <strong>nodes</strong> () const;
   void <strong>add_node</strong> (std::pair&lt;std::string, int&gt; const&amp; node);
   bool <strong>parse_info_section</strong> (bdecode_node const&amp; e, error_code&amp; ec, int flags);
   bdecode_node <strong>info</strong> (char const* key) const;
   void <strong>swap</strong> (torrent_info&amp; ti);
   int <strong>metadata_size</strong> () const;
   boost::shared_array&lt;char&gt; <strong>metadata</strong> () const;
   bool <strong>is_merkle_torrent</strong> () const;
   bool <strong>parse_torrent_file</strong> (bdecode_node const&amp; libtorrent, error_code&amp; ec, int flags);
};
</pre>
<a name="torrent_info()"></a><div class="section" id="id298">
<h3>torrent_info()</h3>
<pre class="literal-block">
<strong>torrent_info</strong> (std::string const&amp; filename, int flags = 0);
<strong>torrent_info</strong> (std::string const&amp; filename, error_code&amp; ec, int flags = 0);
<strong>torrent_info</strong> (char const* buffer, int size, error_code&amp; ec, int flags = 0);
<strong>torrent_info</strong> (sha1_hash const&amp; info_hash, int flags = 0);
<strong>torrent_info</strong> (bdecode_node const&amp; torrent_file, error_code&amp; ec, int flags = 0);
<strong>torrent_info</strong> (char const* buffer, int size, int flags = 0);
<strong>torrent_info</strong> (bdecode_node const&amp; torrent_file, int flags = 0);
<strong>torrent_info</strong> (torrent_info const&amp; t);
</pre>
<p>The constructor that takes an info-hash  will initialize the info-hash
to the given value, but leave all other fields empty. This is used
internally when downloading torrents without the metadata. The
metadata will be created by libtorrent as soon as it has been
downloaded from the swarm.</p>
<p>The constructor that takes a <a class="reference external" href="reference-Bdecoding.html#bdecode_node">bdecode_node</a> will create a <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a>
object from the information found in the given torrent_file. The
<a class="reference external" href="reference-Bdecoding.html#bdecode_node">bdecode_node</a> represents a tree node in an bencoded file. To load an
ordinary .torrent file into a <a class="reference external" href="reference-Bdecoding.html#bdecode_node">bdecode_node</a>, use <a class="reference external" href="reference-Bencoding.html#bdecode()">bdecode()</a>.</p>
<p>The version that takes a buffer pointer and a size will decode it as a
.torrent file and initialize the <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object for you.</p>
<p>The version that takes a filename will simply load the torrent file
and decode it inside the constructor, for convenience. This might not
be the most suitable for applications that want to be able to report
detailed errors on what might go wrong.</p>
<p>There is an upper limit on the size of the torrent file that will be
loaded by the overload taking a filename. If it's important that even
very large torrent files are loaded, use one of the other overloads.</p>
<p>The overloads that takes an <tt class="docutils literal">error_code const&amp;</tt> never throws if an
error occur, they will simply set the error code to describe what went
wrong and not fully initialize the <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object. The overloads
that do not take the extra error_code parameter will always throw if
an error occurs. These overloads are not available when building
without exception support.</p>
<p>The <tt class="docutils literal">flags</tt> argument is currently unused.</p>
<a name="~torrent_info()"></a></div>
<div class="section" id="id306">
<h3>~torrent_info()</h3>
<pre class="literal-block">
<strong>~torrent_info</strong> ();
</pre>
<p>frees all storage associated with this <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object</p>
<a name="orig_files()"></a>
<a name="files()"></a></div>
<div class="section" id="orig-files-files">
<h3>orig_files() files()</h3>
<pre class="literal-block">
file_storage const&amp; <strong>files</strong> () const;
file_storage const&amp; <strong>orig_files</strong> () const;
</pre>
<p>The <a class="reference external" href="reference-Storage.html#file_storage">file_storage</a> object contains the information on how to map the
pieces to files. It is separated from the <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object because
when creating torrents a storage object needs to be created without
having a torrent file. When renaming files in a storage, the storage
needs to make its own copy of the <a class="reference external" href="reference-Storage.html#file_storage">file_storage</a> in order to make its
mapping differ from the one in the torrent file.</p>
<p><tt class="docutils literal">orig_files()</tt> returns the original (unmodified) file storage for
this torrent. This is used by the web server connection, which needs
to request files with the original names. Filename may be changed using
<tt class="docutils literal"><span class="pre">torrent_info::rename_file()</span></tt>.</p>
<p>For more information on the <a class="reference external" href="reference-Storage.html#file_storage">file_storage</a> object, see the separate
document on how to create torrents.</p>
<a name="rename_file()"></a></div>
<div class="section" id="id312">
<h3>rename_file()</h3>
<pre class="literal-block">
void <strong>rename_file</strong> (int index, std::string const&amp; new_filename);
</pre>
<p>Renames a the file with the specified index to the new name. The new
filename is reflected by the <tt class="docutils literal">file_storage</tt> returned by <tt class="docutils literal">files()</tt>
but not by the one returned by <tt class="docutils literal">orig_files()</tt>.</p>
<p>If you want to rename the base name of the torrent (for a multi file
torrent), you can copy the <tt class="docutils literal">file_storage</tt> (see <a class="reference external" href="reference-Core.html#files()">files()</a> and
<a class="reference external" href="reference-Core.html#orig_files()">orig_files()</a> ), change the name, and then use <a class="reference internal" href="#remap-files">remap_files()</a>.</p>
<p>The <tt class="docutils literal">new_filename</tt> can both be a relative path, in which case the
file name is relative to the <tt class="docutils literal">save_path</tt> of the torrent. If the
<tt class="docutils literal">new_filename</tt> is an absolute path (i.e. <tt class="docutils literal">is_complete(new_filename)
== true</tt>), then the file is detached from the <tt class="docutils literal">save_path</tt> of the
torrent. In this case the file is not moved when <a class="reference external" href="reference-Core.html#move_storage()">move_storage()</a> is
invoked.</p>
<a name="remap_files()"></a></div>
<div class="section" id="remap-files">
<h3>remap_files()</h3>
<pre class="literal-block">
void <strong>remap_files</strong> (file_storage const&amp; f);
</pre>
<p>Remaps the file storage to a new file layout. This can be used to, for
instance, download all data in a torrent to a single file, or to a
number of fixed size sector aligned files, regardless of the number
and sizes of the files in the torrent.</p>
<p>The new specified <tt class="docutils literal">file_storage</tt> must have the exact same size as
the current one.</p>
<a name="trackers()"></a>
<a name="add_tracker()"></a></div>
<div class="section" id="trackers-add-tracker">
<h3>trackers() add_tracker()</h3>
<pre class="literal-block">
std::vector&lt;announce_entry&gt; const&amp; <strong>trackers</strong> () const;
void <strong>add_tracker</strong> (std::string const&amp; url, int tier = 0);
</pre>
<p><tt class="docutils literal">add_tracker()</tt> adds a tracker to the announce-list. The <tt class="docutils literal">tier</tt>
determines the order in which the trackers are to be tried.</p>
<p>The <tt class="docutils literal">trackers()</tt> function will return a sorted vector of
<tt class="docutils literal">announce_entry</tt>. Each announce <a class="reference external" href="reference-Bencoding.html#entry">entry</a> contains a string, which is
the tracker url, and a tier index. The tier index is the high-level
priority. No matter which trackers that works or not, the ones with
lower tier will always be tried before the one with higher tier
number. For more information, see <a class="reference internal" href="#announce-entry">announce_entry</a>.</p>
<a name="collections()"></a>
<a name="similar_torrents()"></a></div>
<div class="section" id="collections-similar-torrents">
<h3>collections() similar_torrents()</h3>
<pre class="literal-block">
std::vector&lt;sha1_hash&gt; <strong>similar_torrents</strong> () const;
std::vector&lt;std::string&gt; <strong>collections</strong> () const;
</pre>
<p>These two functions are related to <a class="reference external" href="http://www.bittorrent.org/beps/bep_0038.html">BEP 38</a> (mutable torrents). The
vectors returned from these correspond to the &quot;similar&quot; and
&quot;collections&quot; keys in the .torrent file. Both info-hashes and
collections from within the info-dict and from outside of it are
included.</p>
<a name="add_url_seed()"></a>
<a name="set_web_seeds()"></a>
<a name="add_http_seed()"></a>
<a name="web_seeds()"></a></div>
<div class="section" id="add-url-seed-set-web-seeds-add-http-seed-web-seeds">
<h3>add_url_seed() set_web_seeds() add_http_seed() web_seeds()</h3>
<pre class="literal-block">
void <strong>add_url_seed</strong> (std::string const&amp; url
      , std::string const&amp; extern_auth = std::string()
      , web_seed_entry::headers_t const&amp; extra_headers = web_seed_entry::headers_t());
std::vector&lt;web_seed_entry&gt; const&amp; <strong>web_seeds</strong> () const;
void <strong>set_web_seeds</strong> (std::vector&lt;web_seed_entry&gt; seeds);
void <strong>add_http_seed</strong> (std::string const&amp; url
      , std::string const&amp; extern_auth = std::string()
      , web_seed_entry::headers_t const&amp; extra_headers = web_seed_entry::headers_t());
</pre>
<p><tt class="docutils literal">web_seeds()</tt> returns all url seeds and http seeds in the torrent.
Each <a class="reference external" href="reference-Bencoding.html#entry">entry</a> is a <tt class="docutils literal">web_seed_entry</tt> and may refer to either a url seed
or http seed.</p>
<p><tt class="docutils literal">add_url_seed()</tt> and <tt class="docutils literal">add_http_seed()</tt> adds one url to the list of
url/http seeds. Currently, the only transport protocol supported for
the url is http.</p>
<p><tt class="docutils literal">set_web_seeds()</tt> replaces all web seeds with the ones specified in
the <tt class="docutils literal">seeds</tt> vector.</p>
<p>The <tt class="docutils literal">extern_auth</tt> argument can be used for other authorization
schemes than basic HTTP authorization. If set, it will override any
username and password found in the URL itself. The string will be sent
as the HTTP authorization header's value (without specifying &quot;Basic&quot;).</p>
<p>The <tt class="docutils literal">extra_headers</tt> argument defaults to an empty list, but can be
used to insert custom HTTP headers in the requests to a specific web
seed.</p>
<p>See <a class="reference external" href="manual-ref.html#http-seeding">http seeding</a> for more information.</p>
<a name="piece_length()"></a>
<a name="num_pieces()"></a>
<a name="total_size()"></a></div>
<div class="section" id="piece-length-num-pieces-total-size">
<h3>piece_length() num_pieces() total_size()</h3>
<pre class="literal-block">
boost::int64_t <strong>total_size</strong> () const;
int <strong>num_pieces</strong> () const;
int <strong>piece_length</strong> () const;
</pre>
<p><tt class="docutils literal">total_size()</tt>, <tt class="docutils literal">piece_length()</tt> and <tt class="docutils literal">num_pieces()</tt> returns the
total number of bytes the torrent-file represents (all the files in
it), the number of byte for each piece and the total number of pieces,
respectively. The difference between <tt class="docutils literal">piece_size()</tt> and
<tt class="docutils literal">piece_length()</tt> is that <tt class="docutils literal">piece_size()</tt> takes the piece index as
argument and gives you the exact size of that piece. It will always be
the same as <tt class="docutils literal">piece_length()</tt> except in the case of the last piece,
which may be smaller.</p>
<a name="info_hash()"></a></div>
<div class="section" id="id319">
<h3>info_hash()</h3>
<pre class="literal-block">
const sha1_hash&amp; <strong>info_hash</strong> () const;
</pre>
<p>returns the info-hash of the torrent</p>
<a name="num_files()"></a></div>
<div class="section" id="num-files">
<h3>num_files()</h3>
<pre class="literal-block">
int <strong>num_files</strong> () const;
</pre>
<p>If you need index-access to files you can use the <tt class="docutils literal">num_files()</tt> along
with the <tt class="docutils literal">file_path()</tt>, <tt class="docutils literal">file_size()</tt>-family of functions to access
files using indices.</p>
<a name="map_block()"></a></div>
<div class="section" id="map-block">
<h3>map_block()</h3>
<pre class="literal-block">
std::vector&lt;file_slice&gt; <strong>map_block</strong> (int piece, boost::int64_t offset, int size) const;
</pre>
<p>This function will map a piece index, a byte offset within that piece
and a size (in bytes) into the corresponding files with offsets where
that data for that piece is supposed to be stored. See <a class="reference external" href="reference-Storage.html#file_slice">file_slice</a>.</p>
<a name="map_file()"></a></div>
<div class="section" id="map-file">
<h3>map_file()</h3>
<pre class="literal-block">
peer_request <strong>map_file</strong> (int file, boost::int64_t offset, int size) const;
</pre>
<p>This function will map a range in a specific file into a range in the
torrent. The <tt class="docutils literal">file_offset</tt> parameter is the offset in the file,
given in bytes, where 0 is the start of the file. See <a class="reference external" href="reference-Core.html#peer_request">peer_request</a>.</p>
<p>The input range is assumed to be valid within the torrent.
<tt class="docutils literal">file_offset</tt> + <tt class="docutils literal">size</tt> is not allowed to be greater than the file
size. <tt class="docutils literal">file_index</tt> must refer to a valid file, i.e. it cannot be &gt;=
<tt class="docutils literal">num_files()</tt>.</p>
<a name="unload()"></a>
<a name="load()"></a></div>
<div class="section" id="unload-load">
<h3>unload() load()</h3>
<pre class="literal-block">
void <strong>unload</strong> ();
void <strong>load</strong> (char const* buffer, int size, error_code&amp; ec);
</pre>
<p>load and unload this torrent info</p>
<a name="ssl_cert()"></a></div>
<div class="section" id="ssl-cert">
<h3>ssl_cert()</h3>
<pre class="literal-block">
std::string <strong>ssl_cert</strong> () const;
</pre>
<p>Returns the SSL root certificate for the torrent, if it is an SSL
torrent. Otherwise returns an empty string. The certificate is
the the public certificate in x509 format.</p>
<a name="is_valid()"></a></div>
<div class="section" id="id322">
<h3>is_valid()</h3>
<pre class="literal-block">
bool <strong>is_valid</strong> () const;
</pre>
<p>returns true if this <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object has a torrent loaded.
This is primarily used to determine if a magnet link has had its
metadata resolved yet or not.</p>
<a name="priv()"></a></div>
<div class="section" id="priv">
<h3>priv()</h3>
<pre class="literal-block">
bool <strong>priv</strong> () const;
</pre>
<p>returns true if this torrent is private. i.e., it should not be
distributed on the trackerless network (the kademlia DHT).</p>
<a name="is_i2p()"></a></div>
<div class="section" id="is-i2p">
<h3>is_i2p()</h3>
<pre class="literal-block">
bool <strong>is_i2p</strong> () const;
</pre>
<p>returns true if this is an i2p torrent. This is determined by whether
or not it has a tracker whose URL domain name ends with &quot;.i2p&quot;. i2p
torrents disable the DHT and local peer discovery as well as talking
to peers over anything other than the i2p network.</p>
<a name="hash_for_piece_ptr()"></a>
<a name="hash_for_piece()"></a>
<a name="piece_size()"></a></div>
<div class="section" id="hash-for-piece-ptr-hash-for-piece-piece-size">
<h3>hash_for_piece_ptr() hash_for_piece() piece_size()</h3>
<pre class="literal-block">
sha1_hash <strong>hash_for_piece</strong> (int index) const;
char const* <strong>hash_for_piece_ptr</strong> (int index) const;
int <strong>piece_size</strong> (int index) const;
</pre>
<p><tt class="docutils literal">hash_for_piece()</tt> takes a piece-index and returns the 20-bytes
sha1-hash for that piece and <tt class="docutils literal">info_hash()</tt> returns the 20-bytes
sha1-hash for the info-section of the torrent file.
<tt class="docutils literal">hash_for_piece_ptr()</tt> returns a pointer to the 20 byte sha1 digest
for the piece. Note that the string is not null-terminated.</p>
<a name="set_merkle_tree()"></a>
<a name="merkle_tree()"></a></div>
<div class="section" id="set-merkle-tree-merkle-tree">
<h3>set_merkle_tree() merkle_tree()</h3>
<pre class="literal-block">
std::vector&lt;sha1_hash&gt; const&amp; <strong>merkle_tree</strong> () const;
void <strong>set_merkle_tree</strong> (std::vector&lt;sha1_hash&gt;&amp; h);
</pre>
<p><tt class="docutils literal">merkle_tree()</tt> returns a reference to the merkle tree for this
torrent, if any.</p>
<p><tt class="docutils literal">set_merkle_tree()</tt> moves the passed in merkle tree into the
<a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object. i.e. <tt class="docutils literal">h</tt> will not be identical after the call.
You need to set the merkle tree for a torrent that you've just created
(as a merkle torrent). The merkle tree is retrieved from the
<tt class="docutils literal"><span class="pre">create_torrent::merkle_tree()</span></tt> function, and need to be saved
separately from the torrent file itself. Once it's added to
libtorrent, the merkle tree will be persisted in the resume data.</p>
<a name="creator()"></a>
<a name="creation_date()"></a>
<a name="name()"></a>
<a name="comment()"></a></div>
<div class="section" id="creator-creation-date-name-comment">
<h3>creator() creation_date() name() comment()</h3>
<pre class="literal-block">
boost::optional&lt;time_t&gt; <strong>creation_date</strong> () const;
const std::string&amp; <strong>name</strong> () const;
const std::string&amp; <strong>comment</strong> () const;
const std::string&amp; <strong>creator</strong> () const;
</pre>
<p><tt class="docutils literal">name()</tt> returns the name of the torrent.</p>
<p><tt class="docutils literal">comment()</tt> returns the comment associated with the torrent. If
there's no comment, it will return an empty string.
<tt class="docutils literal">creation_date()</tt> returns the creation date of the torrent as time_t
(<a class="reference external" href="http://www.opengroup.org/onlinepubs/009695399/functions/time.html">posix time</a>). If there's no time stamp in the torrent file, the
optional object will be uninitialized.</p>
<p>Both the name and the comment is UTF-8 encoded strings.</p>
<p><tt class="docutils literal">creator()</tt> returns the creator string in the torrent. If there is
no creator string it will return an empty string.</p>
<a name="nodes()"></a></div>
<div class="section" id="nodes">
<h3>nodes()</h3>
<pre class="literal-block">
nodes_t const&amp; <strong>nodes</strong> () const;
</pre>
<p>If this torrent contains any DHT nodes, they are put in this vector in
their original form (host name and port number).</p>
<a name="add_node()"></a></div>
<div class="section" id="add-node">
<h3>add_node()</h3>
<pre class="literal-block">
void <strong>add_node</strong> (std::pair&lt;std::string, int&gt; const&amp; node);
</pre>
<p>This is used when creating torrent. Use this to add a known DHT node.
It may be used, by the client, to bootstrap into the DHT network.</p>
<a name="parse_info_section()"></a></div>
<div class="section" id="parse-info-section">
<h3>parse_info_section()</h3>
<pre class="literal-block">
bool <strong>parse_info_section</strong> (bdecode_node const&amp; e, error_code&amp; ec, int flags);
</pre>
<p>populates the <a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> by providing just the info-dict buffer.
This is used when loading a torrent from a magnet link for instance,
where we only have the info-dict. The <a class="reference external" href="reference-Bdecoding.html#bdecode_node">bdecode_node</a> <tt class="docutils literal">e</tt> points to a
parsed info-dictionary. <tt class="docutils literal">ec</tt> returns an error code if something
fails (typically if the info dictionary is malformed). <tt class="docutils literal">flags</tt> are
currently unused.</p>
<a name="info()"></a></div>
<div class="section" id="info">
<h3>info()</h3>
<pre class="literal-block">
bdecode_node <strong>info</strong> (char const* key) const;
</pre>
<p>This function looks up keys from the info-dictionary of the loaded
torrent file. It can be used to access extension values put in the
.torrent file. If the specified key cannot be found, it returns NULL.</p>
<a name="swap()"></a></div>
<div class="section" id="swap">
<h3>swap()</h3>
<pre class="literal-block">
void <strong>swap</strong> (torrent_info&amp; ti);
</pre>
<p>swap the content of this and <tt class="docutils literal">ti</tt>.</p>
<a name="metadata_size()"></a>
<a name="metadata()"></a></div>
<div class="section" id="metadata-size-metadata">
<h3>metadata_size() metadata()</h3>
<pre class="literal-block">
int <strong>metadata_size</strong> () const;
boost::shared_array&lt;char&gt; <strong>metadata</strong> () const;
</pre>
<p><tt class="docutils literal">metadata()</tt> returns a the raw info section of the torrent file. The size
of the metadata is returned by <tt class="docutils literal">metadata_size()</tt>.</p>
<a name="is_merkle_torrent()"></a></div>
<div class="section" id="is-merkle-torrent">
<h3>is_merkle_torrent()</h3>
<pre class="literal-block">
bool <strong>is_merkle_torrent</strong> () const;
</pre>
<p>returns whether or not this is a merkle torrent.
see <a class="reference external" href="http://bittorrent.org/beps/bep_0030.html">BEP 30</a>.</p>
<a name="add_torrent_params"></a></div>
</div>
<div class="section" id="add-torrent-params">
<h2>add_torrent_params</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/add_torrent_params.hpp">libtorrent/add_torrent_params.hpp</a>&quot;</p>
<p>The <a class="reference external" href="reference-Core.html#add_torrent_params">add_torrent_params</a> is a parameter pack for adding torrents to a
<a class="reference external" href="reference-Core.html#session">session</a>. The key fields when adding a torrent are:</p>
<ul class="simple">
<li>ti - when you have a .torrent file</li>
<li>url - when you have a magnet link</li>
<li>info_hash - when all you have is an info-hash (this is similar to a
magnet link)</li>
</ul>
<p>one of those fields need to be set. Another mandatory field is
<tt class="docutils literal">save_path</tt>. The <a class="reference external" href="reference-Core.html#add_torrent_params">add_torrent_params</a> object is passed into one of the
<tt class="docutils literal"><span class="pre">session::add_torrent()</span></tt> overloads or <tt class="docutils literal"><span class="pre">session::async_add_torrent()</span></tt>.</p>
<p>If you only specify the info-hash, the torrent file will be downloaded
from peers, which requires them to support the metadata extension. For
the metadata extension to work, libtorrent must be built with extensions
enabled (<tt class="docutils literal">TORRENT_DISABLE_EXTENSIONS</tt> must not be defined). It also
takes an optional <tt class="docutils literal">name</tt> argument. This may be left empty in case no
name should be assigned to the torrent. In case it's not, the name is
used for the torrent as long as it doesn't have metadata. See
<tt class="docutils literal"><span class="pre">torrent_handle::name</span></tt>.</p>
<pre class="literal-block">
struct add_torrent_params
{
   <strong>add_torrent_params</strong> (storage_constructor_type sc = default_storage_constructor);

   enum flags_t
   {
      flag_seed_mode,
      flag_override_resume_data,
      flag_upload_mode,
      flag_share_mode,
      flag_apply_ip_filter,
      flag_paused,
      flag_auto_managed,
      flag_duplicate_is_error,
      flag_merge_resume_trackers,
      flag_update_subscribe,
      flag_super_seeding,
      flag_sequential_download,
      flag_use_resume_save_path,
      flag_pinned,
      flag_merge_resume_http_seeds,
      flag_stop_when_ready,
   };

   int version;
   boost::shared_ptr&lt;torrent_info&gt; ti;
   std::vector&lt;std::string&gt; trackers;
   std::vector&lt;std::string&gt; url_seeds;
   std::vector&lt;std::pair&lt;std::string, int&gt; &gt; dht_nodes;
   std::string name;
   std::string save_path;
   std::vector&lt;char&gt; resume_data;
   storage_mode_t storage_mode;
   storage_constructor_type storage;
   void* userdata;
   std::vector&lt;boost::uint8_t&gt; file_priorities;
   std::string trackerid;
   std::string url;
   std::string uuid;
   std::string source_feed_url;
   boost::uint64_t flags;
   sha1_hash info_hash;
   int max_uploads;
   int max_connections;
   int upload_limit;
   int download_limit;
};
</pre>
<a name="add_torrent_params()"></a><div class="section" id="id332">
<h3>add_torrent_params()</h3>
<pre class="literal-block">
<strong>add_torrent_params</strong> (storage_constructor_type sc = default_storage_constructor);
</pre>
<p>The constructor can be used to initialize the storage constructor,
which determines the storage mechanism for the downloaded or seeding
data for the torrent. For more information, see the <tt class="docutils literal">storage</tt> field.</p>
<a name="flags_t"></a></div>
<div class="section" id="id333">
<h3>enum flags_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/add_torrent_params.hpp">libtorrent/add_torrent_params.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="27%" />
<col width="6%" />
<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>flag_seed_mode</td>
<td>1</td>
<td><p class="first">If <tt class="docutils literal">flag_seed_mode</tt> is set, libtorrent will assume that all files
are present for this torrent and that they all match the hashes in
the torrent file. Each time a peer requests to download a block,
the piece is verified against the hash, unless it has been verified
already. If a hash fails, the torrent will automatically leave the
seed mode and recheck all the files. The use case for this mode is
if a torrent is created and seeded, or if the user already know
that the files are complete, this is a way to avoid the initial
file checks, and significantly reduce the startup time.</p>
<p>Setting <tt class="docutils literal">flag_seed_mode</tt> on a torrent without metadata (a
.torrent file) is a no-op and will be ignored.</p>
<p class="last">If resume data is passed in with this torrent, the seed mode saved
in there will override the seed mode you set here.</p>
</td>
</tr>
<tr><td>flag_override_resume_data</td>
<td>2</td>
<td>If <tt class="docutils literal">flag_override_resume_data</tt> is set, flags set for this torrent
in this <tt class="docutils literal">add_torrent_params</tt> object will take precedence over
whatever states are saved in the resume data. For instance, the
<tt class="docutils literal">paused</tt>, <tt class="docutils literal">auto_managed</tt>, <tt class="docutils literal">sequential_download</tt>, <tt class="docutils literal">seed_mode</tt>,
<tt class="docutils literal">super_seeding</tt>, <tt class="docutils literal">max_uploads</tt>, <tt class="docutils literal">max_connections</tt>,
<tt class="docutils literal">upload_limit</tt> and <tt class="docutils literal">download_limit</tt> are all affected by this
flag. The intention of this flag is to have any field in
<a class="reference external" href="reference-Core.html#add_torrent_params">add_torrent_params</a> configuring the torrent override the corresponding
configuration from the resume file, with the one exception of save
resume data, which has its own flag (for historic reasons).
&quot;file_priorities&quot; and &quot;save_path&quot; are not affected by this flag.</td>
</tr>
<tr><td>flag_upload_mode</td>
<td>4</td>
<td><p class="first">If <tt class="docutils literal">flag_upload_mode</tt> is set, the torrent will be initialized in
upload-mode, which means it will not make any piece requests. This
state is typically entered on disk I/O errors, and if the torrent
is also auto managed, it will be taken out of this state
periodically. This mode can be used to avoid race conditions when
adjusting priorities of pieces before allowing the torrent to start
downloading.</p>
<p class="last">If the torrent is auto-managed (<tt class="docutils literal">flag_auto_managed</tt>), the torrent
will eventually be taken out of upload-mode, regardless of how it
got there. If it's important to manually control when the torrent
leaves upload mode, don't make it auto managed.</p>
</td>
</tr>
<tr><td>flag_share_mode</td>
<td>8</td>
<td><p class="first">determines if the torrent should be added in <em>share mode</em> or not.
Share mode indicates that we are not interested in downloading the
torrent, but merely want to improve our share ratio (i.e. increase
it). A torrent started in share mode will do its best to never
download more than it uploads to the swarm. If the swarm does not
have enough demand for upload capacity, the torrent will not
download anything. This mode is intended to be safe to add any
number of torrents to, without manual screening, without the risk
of downloading more than is uploaded.</p>
<p>A torrent in share mode sets the priority to all pieces to 0,
except for the pieces that are downloaded, when pieces are decided
to be downloaded. This affects the progress bar, which might be set
to &quot;100% finished&quot; most of the time. Do not change file or piece
priorities for torrents in share mode, it will make it not work.</p>
<p class="last">The share mode has one setting, the share ratio target, see
<tt class="docutils literal"><span class="pre">settings_pack::share_mode_target</span></tt> for more info.</p>
</td>
</tr>
<tr><td>flag_apply_ip_filter</td>
<td>16</td>
<td>determines if the IP filter should apply to this torrent or not. By
default all torrents are subject to filtering by the IP filter
(i.e. this flag is set by default). This is useful if certain
torrents needs to be exempt for some reason, being an auto-update
torrent for instance.</td>
</tr>
<tr><td>flag_paused</td>
<td>32</td>
<td>specifies whether or not the torrent is to be started in a paused
state. I.e. it won't connect to the tracker or any of the peers
until it's resumed. This is typically a good way of avoiding race
conditions when setting configuration options on torrents before
starting them.</td>
</tr>
<tr><td>flag_auto_managed</td>
<td>64</td>
<td><p class="first">If the torrent is auto-managed (<tt class="docutils literal">flag_auto_managed</tt>), the torrent
may be resumed at any point, regardless of how it paused. If it's
important to manually control when the torrent is paused and
resumed, don't make it auto managed.</p>
<p>If <tt class="docutils literal">flag_auto_managed</tt> is set, the torrent will be queued,
started and seeded automatically by libtorrent. When this is set,
the torrent should also be started as paused. The default queue
order is the order the torrents were added. They are all downloaded
in that order. For more details, see <a class="reference external" href="manual-ref.html#queuing">queuing</a>.</p>
<p class="last">If you pass in resume data, the auto_managed state of the torrent
when the resume data was saved will override the auto_managed state
you pass in here. You can override this by setting
<tt class="docutils literal">override_resume_data</tt>.</p>
</td>
</tr>
<tr><td>flag_duplicate_is_error</td>
<td>128</td>
<td>&nbsp;</td>
</tr>
<tr><td>flag_merge_resume_trackers</td>
<td>256</td>
<td>defaults to off and specifies whether tracker URLs loaded from
resume data should be added to the trackers in the torrent or
replace the trackers. When replacing trackers (i.e. this flag is not
set), any trackers passed in via <a class="reference external" href="reference-Core.html#add_torrent_params">add_torrent_params</a> are also
replaced by any trackers in the resume data. The default behavior is
to have the resume data override the .torrent file _and_ the
trackers added in <a class="reference external" href="reference-Core.html#add_torrent_params">add_torrent_params</a>.</td>
</tr>
<tr><td>flag_update_subscribe</td>
<td>512</td>
<td>on by default and means that this torrent will be part of state
updates when calling <a class="reference external" href="reference-Core.html#post_torrent_updates()">post_torrent_updates()</a>.</td>
</tr>
<tr><td>flag_super_seeding</td>
<td>1024</td>
<td>sets the torrent into super seeding mode. If the torrent is not a
seed, this flag has no effect. It has the same effect as calling
<tt class="docutils literal"><span class="pre">torrent_handle::super_seeding(true)</span></tt> on the torrent handle
immediately after adding it.</td>
</tr>
<tr><td>flag_sequential_download</td>
<td>2048</td>
<td>sets the sequential download state for the torrent. It has the same
effect as calling <tt class="docutils literal"><span class="pre">torrent_handle::sequential_download(true)</span></tt> on
the torrent handle immediately after adding it.</td>
</tr>
<tr><td>flag_use_resume_save_path</td>
<td>4096</td>
<td>if this flag is set, the save path from the resume data file, if
present, is honored. This defaults to not being set, in which
case the save_path specified in <a class="reference external" href="reference-Core.html#add_torrent_params">add_torrent_params</a> is always used.</td>
</tr>
<tr><td>flag_pinned</td>
<td>8192</td>
<td>indicates that this torrent should never be unloaded from RAM, even
if unloading torrents are allowed in general. Setting this makes
the torrent exempt from loading/unloading management.</td>
</tr>
<tr><td>flag_merge_resume_http_seeds</td>
<td>32768</td>
<td>defaults to off and specifies whether web seed URLs loaded from
resume data should be added to the ones in the torrent file or
replace them. No distinction is made between the two different kinds
of web seeds (<a class="reference external" href="https://bittorrent.org/beps/bep_0017.html">BEP 17</a> and <a class="reference external" href="https://bittorrent.org/beps/bep_0019.html">BEP 19</a>). When replacing web seeds
(i.e. when this flag is not set), any web seeds passed in via
<a class="reference external" href="reference-Core.html#add_torrent_params">add_torrent_params</a> are also replaced. The default behavior is to
have any web seeds in the resume data take precedence over whatever
is passed in here as well as the .torrent file.</td>
</tr>
<tr><td>flag_stop_when_ready</td>
<td>16384</td>
<td>the stop when ready flag. Setting this flag is equivalent to calling
<a class="reference external" href="reference-Core.html#stop_when_ready()">torrent_handle::stop_when_ready()</a> immediately after the torrent is
added.</td>
</tr>
</tbody>
</table>
<a name="version"></a><dl class="docutils">
<dt>version</dt>
<dd>filled in by the constructor and should be left untouched. It is used
for forward binary compatibility.</dd>
</dl>
<a name="ti"></a><dl class="docutils">
<dt>ti</dt>
<dd><a class="reference external" href="reference-Core.html#torrent_info">torrent_info</a> object with the torrent to add. Unless the url or
info_hash is set, this is required to be initialized.</dd>
</dl>
<a name="trackers"></a><dl class="docutils">
<dt>trackers</dt>
<dd>If the torrent doesn't have a tracker, but relies on the DHT to find
peers, the <tt class="docutils literal">trackers</tt> can specify tracker URLs for the torrent.</dd>
</dl>
<a name="url_seeds"></a><dl class="docutils">
<dt>url_seeds</dt>
<dd>url seeds to be added to the torrent (<a class="reference external" href="https://bittorrent.org/beps/bep_0017.html">BEP 17</a>).</dd>
</dl>
<a name="dht_nodes"></a>
<a name="name"></a><dl class="docutils">
<dt>dht_nodes  name</dt>
<dd>a list of hostname and port pairs, representing DHT nodes to be added
to the <a class="reference external" href="reference-Core.html#session">session</a> (if DHT is enabled). The hostname may be an IP address.</dd>
</dl>
<a name="save_path"></a><dl class="docutils">
<dt>save_path</dt>
<dd><p class="first">the path where the torrent is or will be stored. Note that this may
also be stored in resume data. If you want the save path saved in
the resume data to be used, you need to set the
flag_use_resume_save_path flag.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">On windows this path (and other paths) are interpreted as UNC
paths. This means they must use backslashes as directory separators
and may not contain the special directories &quot;.&quot; or &quot;..&quot;.</p>
</div>
<p class="last">Setting this to an absolute path performs slightly better than a
relative path.</p>
</dd>
</dl>
<a name="resume_data"></a><dl class="docutils">
<dt>resume_data</dt>
<dd>The optional parameter, <tt class="docutils literal">resume_data</tt> can be given if up to date
fast-resume data is available. The fast-resume data can be acquired
from a running torrent by calling <a class="reference external" href="reference-Core.html#save_resume_data()">save_resume_data()</a> on
<a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a>. See <a class="reference external" href="manual-ref.html#fast-resume">fast resume</a>. The <tt class="docutils literal">vector</tt> that is passed in
will be swapped into the running torrent instance with
<tt class="docutils literal"><span class="pre">std::vector::swap()</span></tt>.</dd>
</dl>
<a name="storage_mode"></a><dl class="docutils">
<dt>storage_mode</dt>
<dd>One of the values from <a class="reference external" href="reference-Storage.html#storage_mode_t">storage_mode_t</a>. For more information, see
<a class="reference external" href="manual-ref.html#storage-allocation">storage allocation</a>.</dd>
</dl>
<a name="storage"></a><dl class="docutils">
<dt>storage</dt>
<dd>can be used to customize how the data is stored. The default storage
will simply write the data to the files it belongs to, but it could be
overridden to save everything to a single file at a specific location
or encrypt the content on disk for instance. For more information
about the <a class="reference external" href="reference-Custom_Storage.html#storage_interface">storage_interface</a> that needs to be implemented for a custom
storage, see <a class="reference external" href="reference-Custom_Storage.html#storage_interface">storage_interface</a>.</dd>
</dl>
<a name="userdata"></a><dl class="docutils">
<dt>userdata</dt>
<dd>The <tt class="docutils literal">userdata</tt> parameter is optional and will be passed on to the
extension constructor functions, if any
(see <a class="reference external" href="reference-Core.html#add_extension()">torrent_handle::add_extension()</a>).</dd>
</dl>
<a name="file_priorities"></a><dl class="docutils">
<dt>file_priorities</dt>
<dd>can be set to control the initial file priorities when adding a
torrent. The semantics are the same as for
<tt class="docutils literal"><span class="pre">torrent_handle::prioritize_files()</span></tt>. The file priorities specified
in here take precedence over those specified in the resume data, if
any.</dd>
</dl>
<a name="trackerid"></a><dl class="docutils">
<dt>trackerid</dt>
<dd>the default tracker id to be used when announcing to trackers. By
default this is empty, and no tracker ID is used, since this is an
optional argument. If a tracker returns a tracker ID, that ID is used
instead of this.</dd>
</dl>
<a name="url"></a><dl class="docutils">
<dt>url</dt>
<dd>If you specify a <tt class="docutils literal">url</tt>, the torrent will be set in
<tt class="docutils literal">downloading_metadata</tt> state until the .torrent file has been
downloaded. If there's any error while downloading, the torrent will
be stopped and the torrent error state (<tt class="docutils literal"><span class="pre">torrent_status::error</span></tt>)
will indicate what went wrong. The <tt class="docutils literal">url</tt> may be set to a magnet link.</dd>
</dl>
<a name="uuid"></a><dl class="docutils">
<dt>uuid</dt>
<dd>if <tt class="docutils literal">uuid</tt> is specified, it is used to find duplicates. If another
torrent is already running with the same UUID as the one being added,
it will be considered a duplicate. This is mainly useful for RSS feed
items which has UUIDs specified.</dd>
</dl>
<a name="source_feed_url"></a><dl class="docutils">
<dt>source_feed_url</dt>
<dd>should point to the URL of the RSS feed this torrent comes from, if it
comes from an RSS feed.</dd>
</dl>
<a name="flags"></a><dl class="docutils">
<dt>flags</dt>
<dd><p class="first">flags controlling aspects of this torrent and how it's added. See
<a class="reference external" href="reference-Storage.html#flags_t">flags_t</a> for details.</p>
<div class="admonition note last">
<p class="first admonition-title">Note</p>
<p class="last">The <tt class="docutils literal">flags</tt> field is initialized with default flags by the
constructor. In order to preserve default behavior when clearing or
setting other flags, make sure to bitwise OR or in a flag or bitwise
AND the inverse of a flag to clear it.</p>
</div>
</dd>
</dl>
<a name="info_hash"></a><dl class="docutils">
<dt>info_hash</dt>
<dd>set this to the info hash of the torrent to add in case the info-hash
is the only known property of the torrent. i.e. you don't have a
.torrent file nor a magnet link.</dd>
</dl>
<a name="max_uploads"></a>
<a name="max_connections"></a>
<a name="upload_limit"></a>
<a name="download_limit"></a><dl class="docutils">
<dt>max_uploads  max_connections  upload_limit  download_limit</dt>
<dd><p class="first"><tt class="docutils literal">max_uploads</tt>, <tt class="docutils literal">max_connections</tt>, <tt class="docutils literal">upload_limit</tt>,
<tt class="docutils literal">download_limit</tt> correspond to the <tt class="docutils literal">set_max_uploads()</tt>,
<tt class="docutils literal">set_max_connections()</tt>, <tt class="docutils literal">set_upload_limit()</tt> and
<tt class="docutils literal">set_download_limit()</tt> functions on <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a>. These values let
you initialize these settings when the torrent is added, instead of
calling these functions immediately following adding it.</p>
<p>-1 means unlimited on these settings just like their counterpart
functions on <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a></p>
<p class="last">For fine grained control over rate limits depending on various
properties of the peer connection, see <a class="reference external" href="manual-ref.html#peer-classes">peer classes</a>.</p>
</dd>
</dl>
<a name="peer_info"></a></div>
</div>
<div class="section" id="peer-info">
<h2>peer_info</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/peer_info.hpp">libtorrent/peer_info.hpp</a>&quot;</p>
<p>holds information and statistics about one peer
that libtorrent is connected to</p>
<pre class="literal-block">
struct peer_info
{
   enum peer_flags_t
   {
      interesting,
      choked,
      remote_interested,
      remote_choked,
      supports_extensions,
      local_connection,
      handshake,
      connecting,
      on_parole,
      seed,
      optimistic_unchoke,
      snubbed,
      upload_only,
      endgame_mode,
      holepunched,
      i2p_socket,
      utp_socket,
      ssl_socket,
      rc4_encrypted,
      plaintext_encrypted,
   };

   enum peer_source_flags
   {
      tracker,
      dht,
      pex,
      lsd,
      resume_data,
      incoming,
   };

   enum connection_type_t
   {
      standard_bittorrent,
      web_seed,
      http_seed,
   };

   enum bw_state
   {
      bw_idle,
      bw_limit,
      bw_network,
      bw_disk,
   };

   std::string client;
   bitfield pieces;
   boost::int64_t total_download;
   boost::int64_t total_upload;
   time_duration last_request;
   time_duration last_active;
   time_duration download_queue_time;
   boost::uint32_t flags;
   boost::uint32_t source;
   int up_speed;
   int down_speed;
   int payload_up_speed;
   int payload_down_speed;
   peer_id pid;
   int queue_bytes;
   int request_timeout;
   int send_buffer_size;
   int used_send_buffer;
   int receive_buffer_size;
   int used_receive_buffer;
   int num_hashfails;
   int download_queue_length;
   int timed_out_requests;
   int busy_requests;
   int requests_in_buffer;
   int target_dl_queue_length;
   int upload_queue_length;
   int failcount;
   int downloading_piece_index;
   int downloading_block_index;
   int downloading_progress;
   int downloading_total;
   int connection_type;
   int remote_dl_rate;
   int pending_disk_bytes;
   int pending_disk_read_bytes;
   int send_quota;
   int receive_quota;
   int rtt;
   int num_pieces;
   int download_rate_peak;
   int upload_rate_peak;
   float progress;
   int progress_ppm;
   int estimated_reciprocation_rate;
   tcp::endpoint ip;
   tcp::endpoint local_endpoint;
   char read_state;
   char write_state;
};
</pre>
<a name="peer_flags_t"></a><div class="section" id="enum-peer-flags-t">
<h3>enum peer_flags_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/peer_info.hpp">libtorrent/peer_info.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="24%" />
<col width="10%" />
<col width="65%" />
</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>interesting</td>
<td>1</td>
<td><strong>we</strong> are interested in pieces from this peer.</td>
</tr>
<tr><td>choked</td>
<td>2</td>
<td><strong>we</strong> have choked this peer.</td>
</tr>
<tr><td>remote_interested</td>
<td>4</td>
<td>the peer is interested in <strong>us</strong></td>
</tr>
<tr><td>remote_choked</td>
<td>8</td>
<td>the peer has choked <strong>us</strong>.</td>
</tr>
<tr><td>supports_extensions</td>
<td>16</td>
<td>means that this peer supports the
<a class="reference external" href="extension_protocol.html">extension protocol</a>.</td>
</tr>
<tr><td>local_connection</td>
<td>32</td>
<td>The connection was initiated by us, the peer has a
listen port open, and that port is the same as in the
address of this peer. If this flag is not set, this
peer connection was opened by this peer connecting to
us.</td>
</tr>
<tr><td>handshake</td>
<td>64</td>
<td>The connection is opened, and waiting for the
handshake. Until the handshake is done, the peer
cannot be identified.</td>
</tr>
<tr><td>connecting</td>
<td>128</td>
<td>The connection is in a half-open state (i.e. it is
being connected).</td>
</tr>
<tr><td>on_parole</td>
<td>512</td>
<td>The peer has participated in a piece that failed the
hash check, and is now &quot;on parole&quot;, which means we're
only requesting whole pieces from this peer until
it either fails that piece or proves that it doesn't
send bad data.</td>
</tr>
<tr><td>seed</td>
<td>1024</td>
<td>This peer is a seed (it has all the pieces).</td>
</tr>
<tr><td>optimistic_unchoke</td>
<td>2048</td>
<td>This peer is subject to an optimistic unchoke. It has
been unchoked for a while to see if it might unchoke
us in return an earn an upload/unchoke slot. If it
doesn't within some period of time, it will be choked
and another peer will be optimistically unchoked.</td>
</tr>
<tr><td>snubbed</td>
<td>4096</td>
<td>This peer has recently failed to send a block within
the request timeout from when the request was sent.
We're currently picking one block at a time from this
peer.</td>
</tr>
<tr><td>upload_only</td>
<td>8192</td>
<td>This peer has either explicitly (with an extension)
or implicitly (by becoming a seed) told us that it
will not downloading anything more, regardless of
which pieces we have.</td>
</tr>
<tr><td>endgame_mode</td>
<td>16384</td>
<td>This means the last time this peer picket a piece,
it could not pick as many as it wanted because there
were not enough free ones. i.e. all pieces this peer
has were already requested from other peers.</td>
</tr>
<tr><td>holepunched</td>
<td>32768</td>
<td>This flag is set if the peer was in holepunch mode
when the connection succeeded. This typically only
happens if both peers are behind a NAT and the peers
connect via the NAT holepunch mechanism.</td>
</tr>
<tr><td>i2p_socket</td>
<td>65536</td>
<td>indicates that this socket is runnin on top of the
I2P transport.</td>
</tr>
<tr><td>utp_socket</td>
<td>131072</td>
<td>indicates that this socket is a uTP socket</td>
</tr>
<tr><td>ssl_socket</td>
<td>262144</td>
<td>indicates that this socket is running on top of an SSL
(TLS) channel</td>
</tr>
<tr><td>rc4_encrypted</td>
<td>1048576</td>
<td>this connection is obfuscated with RC4</td>
</tr>
<tr><td>plaintext_encrypted</td>
<td>2097152</td>
<td>the handshake of this connection was obfuscated
with a diffie-hellman exchange</td>
</tr>
</tbody>
</table>
<a name="peer_source_flags"></a></div>
<div class="section" id="enum-peer-source-flags">
<h3>enum peer_source_flags</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/peer_info.hpp">libtorrent/peer_info.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="10%" />
<col width="72%" />
</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>tracker</td>
<td>1</td>
<td>The peer was received from the tracker.</td>
</tr>
<tr><td>dht</td>
<td>2</td>
<td>The peer was received from the kademlia DHT.</td>
</tr>
<tr><td>pex</td>
<td>4</td>
<td>The peer was received from the peer exchange
extension.</td>
</tr>
<tr><td>lsd</td>
<td>8</td>
<td>The peer was received from the local service
discovery (The peer is on the local network).</td>
</tr>
<tr><td>resume_data</td>
<td>16</td>
<td>The peer was added from the fast resume data.</td>
</tr>
<tr><td>incoming</td>
<td>32</td>
<td>we received an incoming connection from this peer</td>
</tr>
</tbody>
</table>
<a name="connection_type_t"></a></div>
<div class="section" id="enum-connection-type-t">
<h3>enum connection_type_t</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/peer_info.hpp">libtorrent/peer_info.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="28%" />
<col width="9%" />
<col width="62%" />
</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>standard_bittorrent</td>
<td>0</td>
<td>Regular bittorrent connection</td>
</tr>
<tr><td>web_seed</td>
<td>1</td>
<td>HTTP connection using the <a class="reference external" href="https://bittorrent.org/beps/bep_0019.html">BEP 19</a> protocol</td>
</tr>
<tr><td>http_seed</td>
<td>2</td>
<td>HTTP connection using the <a class="reference external" href="https://bittorrent.org/beps/bep_0017.html">BEP 17</a> protocol</td>
</tr>
</tbody>
</table>
<a name="bw_state"></a></div>
<div class="section" id="enum-bw-state">
<h3>enum bw_state</h3>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/peer_info.hpp">libtorrent/peer_info.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="16%" />
<col width="10%" />
<col width="74%" />
</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>bw_idle</td>
<td>0</td>
<td>The peer is not waiting for any external events to
send or receive data.</td>
</tr>
<tr><td>bw_limit</td>
<td>1</td>
<td>The peer is waiting for the rate limiter.</td>
</tr>
<tr><td>bw_network</td>
<td>2</td>
<td>The peer has quota and is currently waiting for a
network read or write operation to complete. This is
the state all peers are in if there are no bandwidth
limits.</td>
</tr>
<tr><td>bw_disk</td>
<td>4</td>
<td>The peer is waiting for the disk I/O thread to catch
up writing buffers to disk before downloading more.</td>
</tr>
</tbody>
</table>
<a name="client"></a><dl class="docutils">
<dt>client</dt>
<dd>a string describing the software at the other end of the connection.
In some cases this information is not available, then it will contain
a string that may give away something about which software is running
in the other end. In the case of a web seed, the server type and
version will be a part of this string.</dd>
</dl>
<a name="pieces"></a><dl class="docutils">
<dt>pieces</dt>
<dd>a <a class="reference external" href="reference-Utility.html#bitfield">bitfield</a>, with one bit per piece in the torrent. Each bit tells you
if the peer has that piece (if it's set to 1) or if the peer miss that
piece (set to 0).</dd>
</dl>
<a name="total_download"></a>
<a name="total_upload"></a><dl class="docutils">
<dt>total_download  total_upload</dt>
<dd>the total number of bytes downloaded from and uploaded to this peer.
These numbers do not include the protocol chatter, but only the
payload data.</dd>
</dl>
<a name="last_request"></a>
<a name="last_active"></a><dl class="docutils">
<dt>last_request  last_active</dt>
<dd>the time since we last sent a request to this peer and since any
transfer occurred with this peer</dd>
</dl>
<a name="download_queue_time"></a><dl class="docutils">
<dt>download_queue_time</dt>
<dd>the time until all blocks in the request queue will be downloaded</dd>
</dl>
<a name="flags"></a><dl class="docutils">
<dt>flags</dt>
<dd>tells you in which state the peer is in. It is set to
any combination of the <a class="reference external" href="reference-Core.html#peer_flags_t">peer_flags_t</a> enum.</dd>
</dl>
<a name="source"></a><dl class="docutils">
<dt>source</dt>
<dd>a combination of flags describing from which sources this peer
was received. See <a class="reference external" href="reference-Core.html#peer_source_flags">peer_source_flags</a>.</dd>
</dl>
<a name="up_speed"></a>
<a name="down_speed"></a><dl class="docutils">
<dt>up_speed  down_speed</dt>
<dd>the current upload and download speed we have to and from this peer
(including any protocol messages). updated about once per second</dd>
</dl>
<a name="payload_up_speed"></a>
<a name="payload_down_speed"></a><dl class="docutils">
<dt>payload_up_speed  payload_down_speed</dt>
<dd>The transfer rates of payload data only updated about once per second</dd>
</dl>
<a name="pid"></a><dl class="docutils">
<dt>pid</dt>
<dd>the peer's id as used in the bit torrent protocol. This id can be used
to extract 'fingerprints' from the peer. Sometimes it can tell you
which client the peer is using. See identify_client()_</dd>
</dl>
<a name="request_timeout"></a><dl class="docutils">
<dt>request_timeout</dt>
<dd>the number of seconds until the current front piece request will time
out. This timeout can be adjusted through
<tt class="docutils literal"><span class="pre">settings_pack::request_timeout</span></tt>.
-1 means that there is not outstanding request.</dd>
</dl>
<a name="send_buffer_size"></a>
<a name="used_send_buffer"></a><dl class="docutils">
<dt>send_buffer_size  used_send_buffer</dt>
<dd>the number of bytes allocated
and used for the peer's send buffer, respectively.</dd>
</dl>
<a name="receive_buffer_size"></a>
<a name="used_receive_buffer"></a><dl class="docutils">
<dt>receive_buffer_size  used_receive_buffer</dt>
<dd>the number of bytes
allocated and used as receive buffer, respectively.</dd>
</dl>
<a name="num_hashfails"></a><dl class="docutils">
<dt>num_hashfails</dt>
<dd>the number of pieces this peer has participated in sending us that
turned out to fail the hash check.</dd>
</dl>
<a name="download_queue_length"></a><dl class="docutils">
<dt>download_queue_length</dt>
<dd>this is the number of requests we have sent to this peer that we
haven't got a response for yet</dd>
</dl>
<a name="timed_out_requests"></a><dl class="docutils">
<dt>timed_out_requests</dt>
<dd>the number of block requests that have timed out, and are still in the
download queue</dd>
</dl>
<a name="busy_requests"></a><dl class="docutils">
<dt>busy_requests</dt>
<dd>the number of busy requests in the download queue. A busy request is a
request for a block we've also requested from a different peer</dd>
</dl>
<a name="requests_in_buffer"></a><dl class="docutils">
<dt>requests_in_buffer</dt>
<dd>the number of requests messages that are currently in the send buffer
waiting to be sent.</dd>
</dl>
<a name="target_dl_queue_length"></a><dl class="docutils">
<dt>target_dl_queue_length</dt>
<dd>the number of requests that is tried to be maintained (this is
typically a function of download speed)</dd>
</dl>
<a name="upload_queue_length"></a><dl class="docutils">
<dt>upload_queue_length</dt>
<dd>the number of piece-requests we have received from this peer
that we haven't answered with a piece yet.</dd>
</dl>
<a name="failcount"></a><dl class="docutils">
<dt>failcount</dt>
<dd>the number of times this peer has &quot;failed&quot;. i.e. failed to connect or
disconnected us. The failcount is decremented when we see this peer in
a tracker response or peer exchange message.</dd>
</dl>
<a name="downloading_piece_index"></a>
<a name="downloading_block_index"></a>
<a name="downloading_progress"></a>
<a name="downloading_total"></a><dl class="docutils">
<dt>downloading_piece_index  downloading_block_index  downloading_progress  downloading_total</dt>
<dd>You can know which piece, and which part of that piece, that is
currently being downloaded from a specific peer by looking at these
four members. <tt class="docutils literal">downloading_piece_index</tt> is the index of the piece
that is currently being downloaded. This may be set to -1 if there's
currently no piece downloading from this peer. If it is &gt;= 0, the
other three members are valid. <tt class="docutils literal">downloading_block_index</tt> is the
index of the block (or sub-piece) that is being downloaded.
<tt class="docutils literal">downloading_progress</tt> is the number of bytes of this block we have
received from the peer, and <tt class="docutils literal">downloading_total</tt> is the total number
of bytes in this block.</dd>
</dl>
<a name="connection_type"></a><dl class="docutils">
<dt>connection_type</dt>
<dd>the kind of connection this peer uses. See <a class="reference external" href="reference-Core.html#connection_type_t">connection_type_t</a>.</dd>
</dl>
<a name="remote_dl_rate"></a><dl class="docutils">
<dt>remote_dl_rate</dt>
<dd>an estimate of the rate this peer is downloading at, in
bytes per second.</dd>
</dl>
<a name="pending_disk_bytes"></a><dl class="docutils">
<dt>pending_disk_bytes</dt>
<dd>the number of bytes this peer has pending in the disk-io thread.
Downloaded and waiting to be written to disk. This is what is capped
by <tt class="docutils literal"><span class="pre">settings_pack::max_queued_disk_bytes</span></tt>.</dd>
</dl>
<a name="pending_disk_read_bytes"></a><dl class="docutils">
<dt>pending_disk_read_bytes</dt>
<dd>number of outstanding bytes to read
from disk</dd>
</dl>
<a name="send_quota"></a>
<a name="receive_quota"></a><dl class="docutils">
<dt>send_quota  receive_quota</dt>
<dd>the number of bytes this peer has been assigned to be allowed to send
and receive until it has to request more quota from the bandwidth
manager.</dd>
</dl>
<a name="rtt"></a><dl class="docutils">
<dt>rtt</dt>
<dd>an estimated round trip time to this peer, in milliseconds. It is
estimated by timing the the TCP <tt class="docutils literal">connect()</tt>. It may be 0 for
incoming connections.</dd>
</dl>
<a name="num_pieces"></a><dl class="docutils">
<dt>num_pieces</dt>
<dd>the number of pieces this peer has.</dd>
</dl>
<a name="download_rate_peak"></a>
<a name="upload_rate_peak"></a><dl class="docutils">
<dt>download_rate_peak  upload_rate_peak</dt>
<dd>the highest download and upload rates seen on this connection. They
are given in bytes per second. This number is reset to 0 on reconnect.</dd>
</dl>
<a name="progress"></a><dl class="docutils">
<dt>progress</dt>
<dd>the progress of the peer in the range [0, 1]. This is always 0 when
floating point operations are disabled, instead use <tt class="docutils literal">progress_ppm</tt>.</dd>
</dl>
<a name="progress_ppm"></a><dl class="docutils">
<dt>progress_ppm</dt>
<dd>indicates the download progress of the peer in the range [0, 1000000]
(parts per million).</dd>
</dl>
<a name="estimated_reciprocation_rate"></a><dl class="docutils">
<dt>estimated_reciprocation_rate</dt>
<dd>this is an estimation of the upload rate, to this peer, where it will
unchoke us. This is a coarse estimation based on the rate at which
we sent right before we were choked. This is primarily used for the
bittyrant choking algorithm.</dd>
</dl>
<a name="ip"></a><dl class="docutils">
<dt>ip</dt>
<dd>the IP-address to this peer. The type is an asio endpoint. For
more info, see the <a class="reference external" href="http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html">asio</a> documentation.</dd>
</dl>
<a name="local_endpoint"></a><dl class="docutils">
<dt>local_endpoint</dt>
<dd>the IP and port pair the socket is bound to locally. i.e. the IP
address of the interface it's going out over. This may be useful for
multi-homed clients with multiple interfaces to the internet.</dd>
</dl>
<a name="read_state"></a>
<a name="write_state"></a><dl class="docutils">
<dt>read_state  write_state</dt>
<dd>bitmasks indicating what state this peer
is in with regards to sending and receiving data. The states are declared in the
<a class="reference external" href="reference-Core.html#bw_state">bw_state</a> enum.</dd>
</dl>
<a name="peer_request"></a></div>
</div>
<div class="section" id="peer-request">
<h2>peer_request</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/peer_request.hpp">libtorrent/peer_request.hpp</a>&quot;</p>
<p>represents a byte range within a piece. Internally this is
is used for incoming piece requests.</p>
<pre class="literal-block">
struct peer_request
{
   bool <strong>operator==</strong> (peer_request const&amp; r) const;

   int piece;
   int start;
   int length;
};
</pre>
<a name="operator==()"></a><div class="section" id="id369">
<h3>operator==()</h3>
<pre class="literal-block">
bool <strong>operator==</strong> (peer_request const&amp; r) const;
</pre>
<p>returns true if the right hand side <a class="reference external" href="reference-Core.html#peer_request">peer_request</a> refers to the same
range as this does.</p>
<a name="piece"></a><dl class="docutils">
<dt>piece</dt>
<dd>the index of the piece in which the range starts.</dd>
</dl>
<a name="start"></a><dl class="docutils">
<dt>start</dt>
<dd>the offset within that piece where the range starts.</dd>
</dl>
<a name="length"></a><dl class="docutils">
<dt>length</dt>
<dd>the size of the range, in bytes.</dd>
</dl>
<a name="dht_storage_counters"></a></div>
</div>
<div class="section" id="dht-storage-counters">
<h2>dht_storage_counters</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/kademlia/dht_storage.hpp">libtorrent/kademlia/dht_storage.hpp</a>&quot;</p>
<p>This structure hold the relevant counters for the storage</p>
<pre class="literal-block">
struct dht_storage_counters
{
   boost::int32_t torrents;
   boost::int32_t peers;
   boost::int32_t immutable_data;
   boost::int32_t mutable_data;
};
</pre>
<a name="dht_storage_interface"></a></div>
<div class="section" id="dht-storage-interface">
<h2>dht_storage_interface</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/kademlia/dht_storage.hpp">libtorrent/kademlia/dht_storage.hpp</a>&quot;</p>
<p>The DHT storage interface is a pure virtual class that can
be implemented to customize how the data for the DHT is stored.</p>
<p>The default storage implementation uses three maps in RAM to save
the peers, mutable and immutable items and it's designed to
provide a fast and fully compliant behavior of the BEPs.</p>
<p>libtorrent comes with one built-in storage implementation:
<tt class="docutils literal">dht_default_storage</tt> (private non-accessible class). Its
constructor function is called <a class="reference external" href="reference-Core.html#dht_default_storage_constructor()">dht_default_storage_constructor()</a>.</p>
<pre class="literal-block">
struct dht_storage_interface
{
   virtual bool <strong>get_peers</strong> (sha1_hash const&amp; info_hash
      , bool noseed, bool scrape
      , entry&amp; peers) const = 0;
   virtual void <strong>announce_peer</strong> (sha1_hash const&amp; info_hash
      , tcp::endpoint const&amp; endp
      , std::string const&amp; name, bool seed) = 0;
   virtual bool <strong>get_immutable_item</strong> (sha1_hash const&amp; target
      , entry&amp; item) const = 0;
   virtual void <strong>put_immutable_item</strong> (sha1_hash const&amp; target
      , char const* buf, int size
      , address const&amp; addr) = 0;
   virtual bool <strong>get_mutable_item_seq</strong> (sha1_hash const&amp; target
      , boost::int64_t&amp; seq) const = 0;
   virtual bool <strong>get_mutable_item</strong> (sha1_hash const&amp; target
      , boost::int64_t seq, bool force_fill
      , entry&amp; item) const = 0;
   virtual void <strong>put_mutable_item</strong> (sha1_hash const&amp; target
      , char const* buf, int size
      , char const* sig
      , boost::int64_t seq
      , char const* pk
      , char const* salt, int salt_size
      , address const&amp; addr) = 0;
   virtual void <strong>tick</strong> () = 0;
   virtual dht_storage_counters <strong>counters</strong> () const = 0;
   virtual <strong>~dht_storage_interface</strong> ();
};
</pre>
<a name="get_peers()"></a><div class="section" id="get-peers">
<h3>get_peers()</h3>
<pre class="literal-block">
virtual bool <strong>get_peers</strong> (sha1_hash const&amp; info_hash
      , bool noseed, bool scrape
      , entry&amp; peers) const = 0;
</pre>
<p>This function retrieve the peers tracked by the DHT
corresponding to the given info_hash. You can specify if
you want only seeds and/or you are scraping the data.</p>
<p>For future implementers:
If the torrent tracked contains a name, such a name
must be stored as a string in peers[&quot;n&quot;]</p>
<p>If the scrape parameter is true, you should fill these keys:</p>
<pre class="literal-block">
peers[&quot;BFpe&quot;] - with the standard bit representation of a
                256 bloom filter containing the downloaders
peers[&quot;BFsd&quot;] - with the standard bit representation of a
                256 bloom filter containing the seeders
</pre>
<p>If the scrape parameter is false, you should fill the
key peers[&quot;values&quot;] with a list containing a subset of
peers tracked by the given info_hash. Such a list should
consider the value of <a class="reference external" href="reference-Settings.html#max_peers_reply">dht_settings::max_peers_reply</a>.
If noseed is true only peers marked as no seed should be included.</p>
<p>returns true if an <a class="reference external" href="reference-Bencoding.html#entry">entry</a> with the info_hash is found and
the data is returned inside the (<a class="reference external" href="reference-Bencoding.html#entry">entry</a>) out parameter peers.</p>
<a name="announce_peer()"></a></div>
<div class="section" id="announce-peer">
<h3>announce_peer()</h3>
<pre class="literal-block">
virtual void <strong>announce_peer</strong> (sha1_hash const&amp; info_hash
      , tcp::endpoint const&amp; endp
      , std::string const&amp; name, bool seed) = 0;
</pre>
<p>This function is named announce_peer for consistency with the
upper layers, but has nothing to do with networking. Its only
responsibility is store the peer in such a way that it's returned
in the <a class="reference external" href="reference-Bencoding.html#entry">entry</a> with the lookup_peers.</p>
<p>The <tt class="docutils literal">name</tt> parameter is the name of the torrent if provided in
the announce_peer DHT message. The length of this value should
have a maximum length in the final storage. The default
implementation truncate the value for a maximum of 50 characters.</p>
<a name="get_immutable_item()"></a></div>
<div class="section" id="get-immutable-item">
<h3>get_immutable_item()</h3>
<pre class="literal-block">
virtual bool <strong>get_immutable_item</strong> (sha1_hash const&amp; target
      , entry&amp; item) const = 0;
</pre>
<p>This function retrieves the immutable item given its target hash.</p>
<p>For future implementers:
The value should be returned as an <a class="reference external" href="reference-Bencoding.html#entry">entry</a> in the key item[&quot;v&quot;].</p>
<p>returns true if the item is found and the data is returned
inside the (<a class="reference external" href="reference-Bencoding.html#entry">entry</a>) out parameter item.</p>
<a name="put_immutable_item()"></a></div>
<div class="section" id="put-immutable-item">
<h3>put_immutable_item()</h3>
<pre class="literal-block">
virtual void <strong>put_immutable_item</strong> (sha1_hash const&amp; target
      , char const* buf, int size
      , address const&amp; addr) = 0;
</pre>
<p>Store the item's data. This layer is only for storage.
The authentication of the item is performed by the upper layer.</p>
<p>For implementers:
This data can be stored only if the target is not already
present. The implementation should consider the value of
<a class="reference external" href="reference-Settings.html#max_dht_items">dht_settings::max_dht_items</a>.</p>
<a name="get_mutable_item_seq()"></a></div>
<div class="section" id="get-mutable-item-seq">
<h3>get_mutable_item_seq()</h3>
<pre class="literal-block">
virtual bool <strong>get_mutable_item_seq</strong> (sha1_hash const&amp; target
      , boost::int64_t&amp; seq) const = 0;
</pre>
<p>This function retrieves the sequence number of a mutable item.</p>
<p>returns true if the item is found and the data is returned
inside the out parameter seq.</p>
<a name="get_mutable_item()"></a></div>
<div class="section" id="get-mutable-item">
<h3>get_mutable_item()</h3>
<pre class="literal-block">
virtual bool <strong>get_mutable_item</strong> (sha1_hash const&amp; target
      , boost::int64_t seq, bool force_fill
      , entry&amp; item) const = 0;
</pre>
<p>This function retrieves the mutable stored in the DHT.</p>
<p>For implementers:
The item sequence should be stored in the key item[&quot;seq&quot;].
if force_fill is true or (0 &lt;= seq and seq &lt; item[&quot;seq&quot;])
the following keys should be filled
item[&quot;v&quot;] - with the value no encoded.
item[&quot;sig&quot;] - with a string representation of the signature.
item[&quot;k&quot;] - with a string representation of the public key.</p>
<p>returns true if the item is found and the data is returned
inside the (<a class="reference external" href="reference-Bencoding.html#entry">entry</a>) out parameter item.</p>
<a name="put_mutable_item()"></a></div>
<div class="section" id="put-mutable-item">
<h3>put_mutable_item()</h3>
<pre class="literal-block">
virtual void <strong>put_mutable_item</strong> (sha1_hash const&amp; target
      , char const* buf, int size
      , char const* sig
      , boost::int64_t seq
      , char const* pk
      , char const* salt, int salt_size
      , address const&amp; addr) = 0;
</pre>
<p>Store the item's data. This layer is only for storage.
The authentication of the item is performed by the upper layer.</p>
<p>For implementers:
The sequence number should be checked if the item is already
present. The implementation should consider the value of
<a class="reference external" href="reference-Settings.html#max_dht_items">dht_settings::max_dht_items</a>.</p>
<a name="tick()"></a></div>
<div class="section" id="tick">
<h3>tick()</h3>
<pre class="literal-block">
virtual void <strong>tick</strong> () = 0;
</pre>
<p>This function is called periodically (non-constant frequency).</p>
<p>For implementers:
Use this functions for expire peers or items or any other
storage cleanup.</p>
<a name="session_stats_metrics()"></a></div>
</div>
<div class="section" id="session-stats-metrics">
<h2>session_stats_metrics()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/session_stats.hpp">libtorrent/session_stats.hpp</a>&quot;</p>
<pre class="literal-block">
std::vector&lt;stats_metric&gt; <strong>session_stats_metrics</strong> ();
</pre>
<p>This free function returns the list of available metrics exposed by
libtorrent's statistics API. Each metric has a name and a <em>value index</em>.
The value index is the index into the array in <a class="reference external" href="reference-Alerts.html#session_stats_alert">session_stats_alert</a> where
this metric's value can be found when the <a class="reference external" href="reference-Core.html#session">session</a> stats is sampled (by
calling <a class="reference external" href="reference-Core.html#post_session_stats()">post_session_stats()</a>).</p>
<a name="find_metric_idx()"></a></div>
<div class="section" id="find-metric-idx">
<h2>find_metric_idx()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/session_stats.hpp">libtorrent/session_stats.hpp</a>&quot;</p>
<pre class="literal-block">
int <strong>find_metric_idx</strong> (char const* name);
</pre>
<p>given a name of a metric, this function returns the counter index of it,
or -1 if it could not be found. The counter index is the index into the
values array returned by <a class="reference external" href="reference-Alerts.html#session_stats_alert">session_stats_alert</a>.</p>
<a name="make_magnet_uri()"></a></div>
<div class="section" id="make-magnet-uri">
<h2>make_magnet_uri()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/magnet_uri.hpp">libtorrent/magnet_uri.hpp</a>&quot;</p>
<pre class="literal-block">
std::string <strong>make_magnet_uri</strong> (torrent_handle const&amp; handle);
std::string <strong>make_magnet_uri</strong> (torrent_info const&amp; info);
</pre>
<p>Generates a magnet URI from the specified torrent. If the torrent
handle is invalid, an empty string is returned.</p>
<p>For more information about magnet links, see <a class="reference external" href="manual-ref.html#magnet-links">magnet links</a>.</p>
<a name="parse_magnet_uri()"></a></div>
<div class="section" id="parse-magnet-uri">
<h2>parse_magnet_uri()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/magnet_uri.hpp">libtorrent/magnet_uri.hpp</a>&quot;</p>
<pre class="literal-block">
void <strong>parse_magnet_uri</strong> (std::string const&amp; uri
   , add_torrent_params&amp; p, error_code&amp; ec);
</pre>
<p>This function parses out information from the magnet link and populates the
<a class="reference external" href="reference-Core.html#add_torrent_params">add_torrent_params</a> object.</p>
<a name="to_hex()"></a></div>
<div class="section" id="to-hex">
<h2>to_hex()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/hex.hpp">libtorrent/hex.hpp</a>&quot;</p>
<pre class="literal-block">
void <strong>to_hex</strong> (char const *in, int len, char* out);
std::string <strong>to_hex</strong> (std::string const&amp; s);
</pre>
<p>The overload taking a <tt class="docutils literal"><span class="pre">std::string</span></tt> converts (binary) the string <tt class="docutils literal">s</tt>
to hexadecimal representation and returns it.
The overload taking a <tt class="docutils literal">char const*</tt> and a length converts the binary
buffer [<tt class="docutils literal">in</tt>, <tt class="docutils literal">in</tt> + len) to hexadecimal and prints it to the buffer
<tt class="docutils literal">out</tt>. The caller is responsible for making sure the buffer pointed to
by <tt class="docutils literal">out</tt> is large enough, i.e. has at least len * 2 bytes of space.</p>
<a name="from_hex()"></a></div>
<div class="section" id="from-hex">
<h2>from_hex()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/hex.hpp">libtorrent/hex.hpp</a>&quot;</p>
<pre class="literal-block">
bool <strong>from_hex</strong> (char const *in, int len, char* out);
</pre>
<p>converts the buffer [<tt class="docutils literal">in</tt>, <tt class="docutils literal">in</tt> + len) from hexadecimal to
binary. The binary output is written to the buffer pointed to
by <tt class="docutils literal">out</tt>. The caller is responsible for making sure the buffer
at <tt class="docutils literal">out</tt> has enough space for the result to be written to, i.e.
(len + 1) / 2 bytes.</p>
<a name="version()"></a></div>
<div class="section" id="version">
<h2>version()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/version.hpp">libtorrent/version.hpp</a>&quot;</p>
<pre class="literal-block">
char const* <strong>version</strong> ();
</pre>
<p>returns the libtorrent version as string form in this format:
&quot;&lt;major&gt;.&lt;minor&gt;.&lt;tiny&gt;.&lt;tag&gt;&quot;</p>
<a name="generate_fingerprint()"></a></div>
<div class="section" id="generate-fingerprint">
<h2>generate_fingerprint()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/fingerprint.hpp">libtorrent/fingerprint.hpp</a>&quot;</p>
<pre class="literal-block">
std::string <strong>generate_fingerprint</strong> (std::string name
   , int major, int minor = 0, int revision = 0, int tag = 0);
</pre>
<p>This is a utility function to produce a client ID fingerprint formatted to
the most common convention.</p>
<p>The name string should contain exactly two characters. These are the
characters unique to your client, used to identify it. Make sure not to
clash with anybody else. Here are some taken id's:</p>
<table border="1" class="docutils">
<colgroup>
<col width="30%" />
<col width="70%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">id chars</th>
<th class="head">client</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>'AZ'</td>
<td>Azureus</td>
</tr>
<tr><td>'LT'</td>
<td>libtorrent (default)</td>
</tr>
<tr><td>'BX'</td>
<td>BittorrentX</td>
</tr>
<tr><td>'MT'</td>
<td>Moonlight Torrent</td>
</tr>
<tr><td>'TS'</td>
<td>Torrent Storm</td>
</tr>
<tr><td>'SS'</td>
<td>Swarm Scope</td>
</tr>
<tr><td>'XT'</td>
<td>Xan Torrent</td>
</tr>
</tbody>
</table>
<p>There's an informal directory of client id's <a class="reference external" href="http://wiki.theory.org/BitTorrentSpecification#peer_id">here</a>.</p>
<p>The <tt class="docutils literal">major</tt>, <tt class="docutils literal">minor</tt>, <tt class="docutils literal">revision</tt> and <tt class="docutils literal">tag</tt> parameters are used to
identify the version of your client.</p>
<a name="hash_value()"></a></div>
<div class="section" id="hash-value">
<h2>hash_value()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p>
<pre class="literal-block">
std::size_t <strong>hash_value</strong> (torrent_status const&amp; ts);
</pre>
<p>allows <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> to be used in unordered_map and unordered_set.</p>
<a name="hash_value()"></a></div>
<div class="section" id="id399">
<h2>hash_value()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/torrent_handle.hpp">libtorrent/torrent_handle.hpp</a>&quot;</p>
<pre class="literal-block">
std::size_t <strong>hash_value</strong> (torrent_handle const&amp; h);
</pre>
<p>for boost::hash (and to support using this type in unordered_map etc.)</p>
<a name="is_utp_stream_logging()"></a></div>
<div class="section" id="is-utp-stream-logging">
<h2>is_utp_stream_logging()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/utp_stream.hpp">libtorrent/utp_stream.hpp</a>&quot;</p>
<pre class="literal-block">
bool <strong>is_utp_stream_logging</strong> ();
</pre>
<a name="set_utp_stream_logging()"></a></div>
<div class="section" id="set-utp-stream-logging">
<h2>set_utp_stream_logging()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/utp_stream.hpp">libtorrent/utp_stream.hpp</a>&quot;</p>
<pre class="literal-block">
void <strong>set_utp_stream_logging</strong> (bool enable);
</pre>
<p>This function should be used at the very beginning and very end of your program.</p>
<a name="verify_message()"></a></div>
<div class="section" id="verify-message">
<h2>verify_message()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/kademlia/msg.hpp">libtorrent/kademlia/msg.hpp</a>&quot;</p>
<pre class="literal-block">
bool <strong>verify_message</strong> (bdecode_node const&amp; msg, key_desc_t const desc[]
   , bdecode_node ret[], int size, char* error, int error_size);
</pre>
<a name="dht_default_storage_constructor()"></a></div>
<div class="section" id="dht-default-storage-constructor">
<h2>dht_default_storage_constructor()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/kademlia/dht_storage.hpp">libtorrent/kademlia/dht_storage.hpp</a>&quot;</p>
<pre class="literal-block">
dht_storage_interface* <strong>dht_default_storage_constructor</strong> (sha1_hash const&amp; id
   , dht_settings const&amp; settings);
</pre>
<a name="sign_mutable_item()"></a></div>
<div class="section" id="sign-mutable-item">
<h2>sign_mutable_item()</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/kademlia/item.hpp">libtorrent/kademlia/item.hpp</a>&quot;</p>
<pre class="literal-block">
void <strong>sign_mutable_item</strong> (
   std::pair&lt;char const*, int&gt; v
   , std::pair&lt;char const*, int&gt; salt
   , boost::uint64_t seq
   , char const* pk
   , char const* sk
   , char* sig);
</pre>
<p>given a byte range <tt class="docutils literal">v</tt> and an optional byte range <tt class="docutils literal">salt</tt>, a
sequence number, public key <tt class="docutils literal">pk</tt> (must be 32 bytes) and a secret key
<tt class="docutils literal">sk</tt> (must be 64 bytes), this function produces a signature which
is written into a 64 byte buffer pointed to by <tt class="docutils literal">sig</tt>. The caller
is responsible for allocating the destination buffer that's passed in
as the <tt class="docutils literal">sig</tt> argument. Typically it would be allocated on the stack.</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>