fix the documentation generation tool to work for flags, and other global constants. Improve documentation
This commit is contained in:
parent
8378c0f55c
commit
55460a60bc
|
@ -28,6 +28,7 @@ for p in paths:
|
|||
functions = []
|
||||
classes = []
|
||||
enums = []
|
||||
constants = {}
|
||||
|
||||
# maps filename to overview description
|
||||
overviews = {}
|
||||
|
@ -251,6 +252,17 @@ def looks_like_variable(line):
|
|||
return False
|
||||
|
||||
|
||||
def looks_like_constant(line):
|
||||
line = line.strip()
|
||||
if line.startswith('inline'):
|
||||
line = line.split('inline')[1]
|
||||
line = line.strip()
|
||||
if not line.startswith('constexpr'):
|
||||
return False
|
||||
line = line.split('constexpr')[1]
|
||||
return looks_like_variable(line)
|
||||
|
||||
|
||||
def looks_like_forward_decl(line):
|
||||
line = line.split('//')[0]
|
||||
line = line.strip()
|
||||
|
@ -338,6 +350,27 @@ def parse_function(lno, lines, filename):
|
|||
return [None, lno]
|
||||
|
||||
|
||||
def add_desc(line):
|
||||
# plain output prints just descriptions and filters out c++ code.
|
||||
# it's used to run spell checker over
|
||||
if plain_output:
|
||||
for s in line.split('\n'):
|
||||
# if the first character is a space, strip it
|
||||
if len(s) > 0 and s[0] == ' ':
|
||||
s = s[1:]
|
||||
global in_code
|
||||
if in_code is not None and not s.startswith(in_code) and len(s) > 1:
|
||||
in_code = None
|
||||
|
||||
if s.strip().startswith('.. code::'):
|
||||
in_code = s.split('.. code::')[0] + '\t'
|
||||
|
||||
# strip out C++ code from the plain text output since it's meant for
|
||||
# running spell checking over
|
||||
if not s.strip().startswith('.. ') and in_code is None:
|
||||
plain_file.write(s + '\n')
|
||||
|
||||
|
||||
def parse_class(lno, lines, filename):
|
||||
start_brace = 0
|
||||
end_brace = 0
|
||||
|
@ -404,24 +437,6 @@ def parse_class(lno, lines, filename):
|
|||
if verbose:
|
||||
print('desc %s' % line)
|
||||
|
||||
# plain output prints just descriptions and filters out c++ code.
|
||||
# it's used to run spell checker over
|
||||
if plain_output:
|
||||
s = line.split('//')[1]
|
||||
# if the first character is a space, strip it
|
||||
if len(s) > 0 and s[0] == ' ':
|
||||
s = s[1:]
|
||||
global in_code
|
||||
if in_code is not None and not s.startswith(in_code) and len(s) > 1:
|
||||
in_code = None
|
||||
|
||||
if s.strip().startswith('.. code::'):
|
||||
in_code = s.split('.. code::')[0] + '\t'
|
||||
|
||||
# strip out C++ code from the plain text output since it's meant for
|
||||
# running spell checking over
|
||||
if not s.strip().startswith('.. ') and in_code is None:
|
||||
plain_file.write(s + '\n')
|
||||
line = line[2:]
|
||||
if len(line) and line[0] == ' ':
|
||||
line = line[1:]
|
||||
|
@ -465,6 +480,7 @@ def parse_class(lno, lines, filename):
|
|||
print('TODO comment in public documentation: %s:%d' % (filename, lno))
|
||||
sys.exit(1)
|
||||
current_fun['desc'] = context
|
||||
add_desc(context)
|
||||
if context == '' and not suppress_warning(filename, first_item(current_fun['names'])):
|
||||
print('WARNING: member function "%s" is not documented: \x1b[34m%s:%d\x1b[0m'
|
||||
% (name + '::' + first_item(current_fun['names']), filename, lno))
|
||||
|
@ -491,6 +507,7 @@ def parse_class(lno, lines, filename):
|
|||
if context == '' and not suppress_warning(filename, n):
|
||||
print('WARNING: field "%s" is not documented: \x1b[34m%s:%d\x1b[0m'
|
||||
% (name + '::' + n, filename, lno))
|
||||
add_desc(context)
|
||||
fields.append({'signatures': [line], 'names': [n], 'desc': context})
|
||||
context = ''
|
||||
blanks = 0
|
||||
|
@ -508,6 +525,7 @@ def parse_class(lno, lines, filename):
|
|||
print('TODO comment in public documentation: %s:%d' % (filename, lno))
|
||||
sys.exit(1)
|
||||
enum['desc'] = context
|
||||
add_desc(context)
|
||||
if context == '' and not suppress_warning(filename, enum['name']):
|
||||
print('WARNING: enum "%s" is not documented: \x1b[34m%s:%d\x1b[0m'
|
||||
% (name + '::' + enum['name'], filename, lno))
|
||||
|
@ -530,6 +548,19 @@ def parse_class(lno, lines, filename):
|
|||
return [None, lno]
|
||||
|
||||
|
||||
def parse_constant(lno, lines, filename):
|
||||
line = lines[lno].strip()
|
||||
if verbose:
|
||||
print('const %s' % line)
|
||||
line = line.split('=')[0]
|
||||
if 'constexpr' in line:
|
||||
line = line.split('constexpr')[1]
|
||||
if '{' in line and '}' in line:
|
||||
line = line.split('{')[0]
|
||||
t, name = line.strip().split(' ')
|
||||
return [{'file': filename[11:], 'type': t, 'name': name}, lno + 1]
|
||||
|
||||
|
||||
def parse_enum(lno, lines, filename):
|
||||
start_brace = 0
|
||||
end_brace = 0
|
||||
|
@ -597,6 +628,7 @@ def parse_enum(lno, lines, filename):
|
|||
if '=' in v:
|
||||
v = v.split('=')[0].strip()
|
||||
if is_visible(context):
|
||||
add_desc(context)
|
||||
values.append({'name': v.strip(), 'desc': context, 'val': valstr})
|
||||
if verbose:
|
||||
print('enumv %s' % valstr)
|
||||
|
@ -800,6 +832,24 @@ for filename in files:
|
|||
print('xx %s' % line)
|
||||
continue
|
||||
|
||||
if looks_like_constant(line):
|
||||
current_constant, lno = parse_constant(lno - 1, lines, filename)
|
||||
if current_constant is not None and is_visible(context):
|
||||
if 'TODO: ' in context:
|
||||
print('TODO comment in public documentation: %s:%d' % (filename, lno))
|
||||
sys.exit(1)
|
||||
current_constant['desc'] = context
|
||||
add_desc(context)
|
||||
if context == '':
|
||||
print('WARNING: constant "%s" is not documented: \x1b[34m%s:%d\x1b[0m'
|
||||
% (current_constant['name'], filename, lno))
|
||||
t = current_constant['type']
|
||||
if t in constants:
|
||||
constants[t].append(current_constant)
|
||||
else:
|
||||
constants[t] = [current_constant]
|
||||
continue
|
||||
|
||||
if 'TORRENT_EXPORT ' in line or line.startswith('inline ') or line.startswith('template') or internal:
|
||||
if line.startswith('class ') or line.startswith('struct '):
|
||||
if not line.endswith(';'):
|
||||
|
@ -809,6 +859,7 @@ for filename in files:
|
|||
print('TODO comment in public documentation: %s:%d' % (filename, lno))
|
||||
sys.exit(1)
|
||||
current_class['desc'] = context
|
||||
add_desc(context)
|
||||
if context == '':
|
||||
print('WARNING: class "%s" is not documented: \x1b[34m%s:%d\x1b[0m'
|
||||
% (current_class['name'], filename, lno))
|
||||
|
@ -828,6 +879,7 @@ for filename in files:
|
|||
print('TODO comment in public documentation: %s:%d' % (filename, lno))
|
||||
sys.exit(1)
|
||||
current_fun['desc'] = context
|
||||
add_desc(context)
|
||||
if context == '':
|
||||
print('WARNING: function "%s" is not documented: \x1b[34m%s:%d\x1b[0m'
|
||||
% (first_item(current_fun['names']), filename, lno))
|
||||
|
@ -852,6 +904,7 @@ for filename in files:
|
|||
print('TODO comment in public documentation: %s:%d' % (filename, lno))
|
||||
sys.exit(1)
|
||||
current_enum['desc'] = context
|
||||
add_desc(context)
|
||||
if context == '':
|
||||
print('WARNING: enum "%s" is not documented: \x1b[34m%s:%d\x1b[0m'
|
||||
% (current_enum['name'], filename, lno))
|
||||
|
@ -879,6 +932,12 @@ for filename in files:
|
|||
# ====================================================================
|
||||
|
||||
|
||||
def new_category(cat):
|
||||
return {'classes': [], 'functions': [], 'enums': [],
|
||||
'filename': 'reference-%s.rst' % cat.replace(' ', '_'),
|
||||
'constants': {}}
|
||||
|
||||
|
||||
if dump:
|
||||
|
||||
if verbose:
|
||||
|
@ -916,13 +975,15 @@ if dump:
|
|||
print(' %s' % v['name'])
|
||||
print('};')
|
||||
|
||||
for t, c in constants:
|
||||
print('\x1b[4mconstant\x1b[0m %s %s\n' % (e['type'], e['name']))
|
||||
|
||||
categories = {}
|
||||
|
||||
for c in classes:
|
||||
cat = categorize_symbol(c['name'], c['file'])
|
||||
if cat not in categories:
|
||||
categories[cat] = {'classes': [], 'functions': [], 'enums': [],
|
||||
'filename': 'reference-%s.rst' % cat.replace(' ', '_')}
|
||||
categories[cat] = new_category(cat)
|
||||
|
||||
if c['file'] in overviews:
|
||||
categories[cat]['overview'] = overviews[c['file']]
|
||||
|
@ -950,8 +1011,7 @@ for c in classes:
|
|||
for f in functions:
|
||||
cat = categorize_symbol(first_item(f['names']), f['file'])
|
||||
if cat not in categories:
|
||||
categories[cat] = {'classes': [], 'functions': [], 'enums': [],
|
||||
'filename': 'reference-%s.rst' % cat.replace(' ', '_')}
|
||||
categories[cat] = new_category(cat)
|
||||
|
||||
if f['file'] in overviews:
|
||||
categories[cat]['overview'] = overviews[f['file']]
|
||||
|
@ -963,14 +1023,26 @@ for f in functions:
|
|||
for e in enums:
|
||||
cat = categorize_symbol(e['name'], e['file'])
|
||||
if cat not in categories:
|
||||
categories[cat] = {'classes': [], 'functions': [], 'enums': [],
|
||||
'filename': 'reference-%s.rst' % cat.replace(' ', '_')}
|
||||
categories[cat] = new_category(cat)
|
||||
categories[cat]['enums'].append(e)
|
||||
filename = categories[cat]['filename'].replace('.rst', '.html') + '#'
|
||||
symbols[e['name']] = filename + e['name']
|
||||
for v in e['values']:
|
||||
symbols[e['name'] + '::' + v['name']] = filename + v['name']
|
||||
|
||||
for t, c in constants.items():
|
||||
for const in c:
|
||||
cat = categorize_symbol(t, const['file'])
|
||||
if cat not in categories:
|
||||
categories[cat] = new_category(cat)
|
||||
if t not in categories[cat]['constants']:
|
||||
categories[cat]['constants'][t] = [const]
|
||||
else:
|
||||
categories[cat]['constants'][t].append(const)
|
||||
filename = categories[cat]['filename'].replace('.rst', '.html') + '#'
|
||||
symbols[t + '::' + const['name']] = filename + t + '::' + const['name']
|
||||
symbols[t] = filename + t
|
||||
|
||||
|
||||
def print_declared_in(out, o):
|
||||
out.write('Declared in "%s"\n\n' % print_link(o['file'], '../include/%s' % o['file']))
|
||||
|
@ -1162,6 +1234,8 @@ def print_toc(out, categories, s):
|
|||
print('\t| ' + print_link(n, symbols[n]), file=out)
|
||||
for e in categories[cat]['enums']:
|
||||
print('\t| ' + print_link(e['name'], symbols[e['name']]), file=out)
|
||||
for t, c in categories[cat]['constants'].items():
|
||||
print('\t| ' + print_link(t, symbols[t]), file=out)
|
||||
print('', file=out)
|
||||
|
||||
if 'overview' in categories[cat]:
|
||||
|
@ -1171,8 +1245,8 @@ def print_toc(out, categories, s):
|
|||
|
||||
def dump_report_issue(h, out):
|
||||
print(('.. raw:: html\n\n\t<span style="float:right;">[<a style="color:blue;" ' +
|
||||
'href="http://github.com/arvidn/libtorrent/issues/new?title=docs:%s&labels=' +
|
||||
'documentation&body=%s">report issue</a>]</span>\n\n').format(
|
||||
'href="http://github.com/arvidn/libtorrent/issues/new?title=docs:{0}&labels=' +
|
||||
'documentation&body={1}">report issue</a>]</span>\n\n').format(
|
||||
urllib.quote_plus(h),
|
||||
urllib.quote_plus('Documentation under heading "' + h + '" could be improved')), file=out)
|
||||
|
||||
|
@ -1199,6 +1273,7 @@ for cat in categories:
|
|||
classes = categories[cat]['classes']
|
||||
functions = categories[cat]['functions']
|
||||
enums = categories[cat]['enums']
|
||||
constants = categories[cat]['constants']
|
||||
|
||||
out.write('''.. include:: header.rst
|
||||
|
||||
|
@ -1321,6 +1396,23 @@ __ reference.html
|
|||
|
||||
render_enums(out, enums, True, '-')
|
||||
|
||||
for t, c in constants.items():
|
||||
print('.. raw:: html\n', file=out)
|
||||
print('\t<a name="%s"></a>\n' % t, file=out)
|
||||
dump_report_issue(t, out)
|
||||
print(heading(t, '-'), file=out)
|
||||
print_declared_in(out, c[0])
|
||||
|
||||
for v in c:
|
||||
print('.. raw:: html\n', file=out)
|
||||
print('\t<a name="%s::%s"></a>\n' % (t, v['name']), file=out)
|
||||
print(v['name'], file=out)
|
||||
v['desc'] = linkify_symbols(v['desc'])
|
||||
print('\t%s' % v['desc'].replace('\n', '\n\t'), file=out)
|
||||
print(dump_link_targets('\t'), file=out)
|
||||
|
||||
print('', file=out)
|
||||
|
||||
print(dump_link_targets(), file=out)
|
||||
|
||||
for i in static_links:
|
||||
|
|
|
@ -8,6 +8,7 @@ SHA-1
|
|||
ed25519
|
||||
const
|
||||
BEP
|
||||
BEPs
|
||||
bdecode
|
||||
bdecoded
|
||||
bencode
|
||||
|
@ -49,6 +50,7 @@ LRU
|
|||
LRUs
|
||||
UPnP
|
||||
NAT
|
||||
NATs
|
||||
PMP
|
||||
arvid
|
||||
Arvid
|
||||
|
@ -212,6 +214,7 @@ nid
|
|||
crypto
|
||||
URI
|
||||
URIs
|
||||
uri
|
||||
infohashes
|
||||
rw
|
||||
holepunch
|
||||
|
@ -438,6 +441,13 @@ todo
|
|||
0x41727101980
|
||||
0x7fffffffffffffff
|
||||
2410d4554d5ed856d69f426c38791673c59f4418
|
||||
E4F0B674
|
||||
0DFC
|
||||
48BB
|
||||
98A5
|
||||
2AA730BDB6D6
|
||||
0x0
|
||||
0x20
|
||||
2e
|
||||
373ZDeQgQSQNuxdinNAPnQ63CRNn4iEXzg
|
||||
BT
|
||||
|
@ -449,8 +459,6 @@ d11
|
|||
de
|
||||
e1
|
||||
impl
|
||||
impl
|
||||
impl
|
||||
md11
|
||||
metadatai0ee
|
||||
metadatai1e6
|
||||
|
@ -513,3 +521,29 @@ chrono
|
|||
hunspell
|
||||
online
|
||||
dic
|
||||
fallocate
|
||||
strdup
|
||||
istream
|
||||
ostream
|
||||
nonrouters
|
||||
backoff
|
||||
atime
|
||||
wildcard
|
||||
sk
|
||||
OutIt
|
||||
OutputIterator
|
||||
udp
|
||||
nat
|
||||
pmp
|
||||
https
|
||||
RemoteHost
|
||||
ExternalPort
|
||||
ret
|
||||
pos
|
||||
os
|
||||
bt
|
||||
cpp
|
||||
tos
|
||||
BP
|
||||
qB
|
||||
LT1230
|
||||
|
|
|
@ -1,4 +1,5 @@
|
|||
#!/bin/python
|
||||
# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4
|
||||
|
||||
import sys
|
||||
|
||||
|
|
|
@ -109,9 +109,9 @@ spell-check:plain_text_out.txt $(MANUAL_TARGETS:=.html) manual.rst settings.rst
|
|||
python filter-rst.py settings.rst >settings-plain.txt
|
||||
python filter-rst.py upgrade_to_1.2.rst >upgrade-1_2-plain.txt
|
||||
hunspell -d hunspell/en_US -p hunspell/libtorrent.dic -l plain_text_out.txt >hunspell-report.txt
|
||||
hunspell -d hunspell/en_US -p hunspell/libtorrent.dic -l manual-plain.txt >hunspell-report.txt
|
||||
hunspell -d hunspell/en_US -p hunspell/libtorrent.dic -l upgrade-1_2-plain.txt >hunspell-report.txt
|
||||
# hunspell -d hunspell/en_US -p hunspell/settings.dic -l settings-plain.txt >hunspell-report.txt
|
||||
hunspell -d hunspell/en_US -p hunspell/libtorrent.dic -l manual-plain.txt >>hunspell-report.txt
|
||||
hunspell -d hunspell/en_US -p hunspell/libtorrent.dic -l upgrade-1_2-plain.txt >>hunspell-report.txt
|
||||
hunspell -d hunspell/en_US -p hunspell/settings.dic -l settings-plain.txt >>hunspell-report.txt
|
||||
hunspell -d hunspell/en_US -p hunspell/libtorrent.dic -H -l $(MANUAL_TARGETS:=.html) >>hunspell-report.txt
|
||||
@if [ -s hunspell-report.txt ]; then echo 'spellcheck failed, fix words or add to dictionary:'; cat hunspell-report.txt; false; fi;
|
||||
|
||||
|
|
|
@ -204,8 +204,9 @@ resume torrents based on certain criteria. The criteria depends on the overall
|
|||
state the torrent is in (checking, downloading or seeding).
|
||||
|
||||
To opt-out of the queuing logic, make sure your torrents are added with the
|
||||
add_torrent_params::flag_auto_managed bit *cleared*. Or call
|
||||
``torrent_handle::auto_managed(false)`` on the torrent handle.
|
||||
torrent_flags::auto_managed bit *cleared* from ``add_torrent_params::flags``.
|
||||
Or call ``torrent_handle::unset_flags(torrent_flags::auto_managed)`` on the
|
||||
torrent handle.
|
||||
|
||||
The overall purpose of the queuing logic is to improve performance under arbitrary
|
||||
torrent downloading and seeding load. For example, if you want to download 100
|
||||
|
|
|
@ -80,7 +80,7 @@ TORRENT_VERSION_NAMESPACE_2
|
|||
//
|
||||
// The ``add_torrent_params`` is also used when requesting resume data for a
|
||||
// torrent. It can be saved to and restored from a file and added back to a
|
||||
// new session. For serialization and deserialization of
|
||||
// new session. For serialization and de-serialization of
|
||||
// ``add_torrent_params`` objects, see read_resume_data() and
|
||||
// write_resume_data().
|
||||
#include "libtorrent/aux_/disable_warnings_push.hpp"
|
||||
|
|
|
@ -436,7 +436,9 @@ TORRENT_VERSION_NAMESPACE_2
|
|||
// or that our send buffer watermark is too small, because we can
|
||||
// send it all before the disk gets back to us.
|
||||
// The number of bytes that we keep outstanding, requested from the disk, is calculated
|
||||
// as follows::
|
||||
// as follows:
|
||||
//
|
||||
// .. code:: C++
|
||||
//
|
||||
// min(512, max(upload_rate * send_buffer_watermark_factor / 100, send_buffer_watermark))
|
||||
//
|
||||
|
@ -715,7 +717,7 @@ TORRENT_VERSION_NAMESPACE_2
|
|||
std::string message() const override;
|
||||
};
|
||||
|
||||
// This alert is generated when a peer is unsnubbed. Essentially when it was snubbed for stalling
|
||||
// This alert is generated when a peer is un-snubbed. Essentially when it was snubbed for stalling
|
||||
// sending data, and now it started sending data again.
|
||||
struct TORRENT_EXPORT peer_unsnubbed_alert final : peer_alert
|
||||
{
|
||||
|
@ -1325,7 +1327,9 @@ TORRENT_VERSION_NAMESPACE_2
|
|||
//
|
||||
// Typically, when receiving this alert, you would want to save the torrent file in order
|
||||
// to load it back up again when the session is restarted. Here's an example snippet of
|
||||
// code to do that::
|
||||
// code to do that:
|
||||
//
|
||||
// .. code:: c++
|
||||
//
|
||||
// torrent_handle h = alert->handle();
|
||||
// if (h.is_valid()) {
|
||||
|
@ -1668,8 +1672,8 @@ TORRENT_VERSION_NAMESPACE_2
|
|||
|
||||
};
|
||||
|
||||
// This alert is generated when a fastresume file has been passed to
|
||||
// add_torrent() but the files on disk did not match the fastresume file.
|
||||
// This alert is generated when a fast resume file has been passed to
|
||||
// add_torrent() but the files on disk did not match the fast resume file.
|
||||
// The error_code explains the reason why the resume file was rejected.
|
||||
struct TORRENT_EXPORT fastresume_rejected_alert final : torrent_alert
|
||||
{
|
||||
|
@ -2033,7 +2037,7 @@ TORRENT_VERSION_NAMESPACE_2
|
|||
|
||||
// This alert is always posted when a torrent was attempted to be added
|
||||
// and contains the return status of the add operation. The torrent handle of the new
|
||||
// torrent can be found in the base class' ``handle`` member. If adding
|
||||
// torrent can be found as the ``handle`` member in the base class. If adding
|
||||
// the torrent failed, ``error`` contains the error code.
|
||||
struct TORRENT_EXPORT add_torrent_alert final : torrent_alert
|
||||
{
|
||||
|
|
|
@ -54,6 +54,7 @@ namespace libtorrent {
|
|||
TORRENT_EXTRA_EXPORT bool is_teredo(address const& addr);
|
||||
TORRENT_EXTRA_EXPORT bool is_ip_address(std::string const& host);
|
||||
|
||||
// internal
|
||||
// TODO: refactor these out too
|
||||
template <typename Endpoint>
|
||||
bool is_v4(Endpoint const& ep)
|
||||
|
|
|
@ -451,8 +451,10 @@ POSSIBILITY OF SUCH DAMAGE.
|
|||
|
||||
#if !defined(TORRENT_READ_HANDLER_MAX_SIZE)
|
||||
# if defined _GLIBCXX_DEBUG || !defined NDEBUG
|
||||
// internal
|
||||
constexpr std::size_t TORRENT_READ_HANDLER_MAX_SIZE = 432;
|
||||
# else
|
||||
// internal
|
||||
// if this is not divisible by 8, we're wasting space
|
||||
constexpr std::size_t TORRENT_READ_HANDLER_MAX_SIZE = 342;
|
||||
# endif
|
||||
|
@ -460,8 +462,10 @@ constexpr std::size_t TORRENT_READ_HANDLER_MAX_SIZE = 342;
|
|||
|
||||
#if !defined(TORRENT_WRITE_HANDLER_MAX_SIZE)
|
||||
# if defined _GLIBCXX_DEBUG || !defined NDEBUG
|
||||
// internal
|
||||
constexpr std::size_t TORRENT_WRITE_HANDLER_MAX_SIZE = 432;
|
||||
# else
|
||||
// internal
|
||||
// if this is not divisible by 8, we're wasting space
|
||||
constexpr std::size_t TORRENT_WRITE_HANDLER_MAX_SIZE = 342;
|
||||
# endif
|
||||
|
|
|
@ -369,7 +369,9 @@ namespace detail {
|
|||
//
|
||||
// If specified, the predicate ``p`` is called once for every file and directory that
|
||||
// is encountered. Files for which ``p`` returns true are added, and directories for
|
||||
// which ``p`` returns true are traversed. ``p`` must have the following signature::
|
||||
// which ``p`` returns true are traversed. ``p`` must have the following signature:
|
||||
//
|
||||
// .. code:: c++
|
||||
//
|
||||
// bool Pred(std::string const& p);
|
||||
//
|
||||
|
@ -389,7 +391,9 @@ namespace detail {
|
|||
// This function will assume that the files added to the torrent file exists at path
|
||||
// ``p``, read those files and hash the content and set the hashes in the ``create_torrent``
|
||||
// object. The optional function ``f`` is called in between every hash that is set. ``f``
|
||||
// must have the following signature::
|
||||
// must have the following signature:
|
||||
//
|
||||
// .. code:: c++
|
||||
//
|
||||
// void Fun(piece_index_t);
|
||||
//
|
||||
|
@ -417,11 +421,11 @@ namespace detail {
|
|||
}
|
||||
#endif
|
||||
|
||||
#if TORRENT_ABI_VERSION == 1
|
||||
|
||||
// all wstring APIs are deprecated since 0.16.11
|
||||
// instead, use the wchar -> utf8 conversion functions
|
||||
// and pass in utf8 strings
|
||||
#if TORRENT_ABI_VERSION == 1
|
||||
|
||||
TORRENT_DEPRECATED_EXPORT
|
||||
void add_files(file_storage& fs, std::wstring const& wfile
|
||||
, std::function<bool(std::string)> p, create_flags_t flags = {});
|
||||
|
|
|
@ -58,6 +58,7 @@ namespace libtorrent {
|
|||
|
||||
using file_open_mode_t = flags::bitfield_flag<std::uint8_t, struct file_open_mode_tag>;
|
||||
|
||||
// internal
|
||||
// this is a bittorrent constant
|
||||
constexpr int default_block_size = 0x4000;
|
||||
|
||||
|
@ -105,7 +106,7 @@ namespace libtorrent {
|
|||
|
||||
// ``open_mode`` is a bitmask of the file flags this file is currently
|
||||
// opened with. These are the flags used in the ``file::open()`` function.
|
||||
// The flags used in this bitfield are defined by the file_open_mode enum.
|
||||
// For possible flags, see file_open_mode_t.
|
||||
//
|
||||
// Note that the read/write mode is not a bitmask. The two least significant bits are used
|
||||
// to represent the read/write mode. Those bits can be masked out using the ``rw_mask`` constant.
|
||||
|
|
|
@ -39,9 +39,17 @@ namespace libtorrent {
|
|||
|
||||
using download_priority_t = aux::strong_typedef<std::uint8_t, struct download_priority_tag>;
|
||||
|
||||
// Don't download the file or piece. Partial pieces may still be downloaded when
|
||||
// setting file priorities.
|
||||
constexpr download_priority_t dont_download{0};
|
||||
|
||||
// The default priority for files and pieces.
|
||||
constexpr download_priority_t default_priority{4};
|
||||
|
||||
// The lowest priority for files and pieces.
|
||||
constexpr download_priority_t low_priority{1};
|
||||
|
||||
// The highest priority for files and pieces.
|
||||
constexpr download_priority_t top_priority{7};
|
||||
|
||||
}
|
||||
|
|
|
@ -111,7 +111,7 @@ namespace libtorrent {
|
|||
unsupported_url_protocol,
|
||||
// The URL did not conform to URL syntax and failed to be parsed
|
||||
url_parse_error,
|
||||
// The peer sent a 'piece' message of length 0
|
||||
// The peer sent a piece message of length 0
|
||||
peer_sent_empty_piece,
|
||||
// A bencoded structure was corrupt and failed to be parsed
|
||||
parse_failed,
|
||||
|
@ -129,7 +129,7 @@ namespace libtorrent {
|
|||
// The port is blocked by the port-filter, and prevented the
|
||||
// connection
|
||||
port_blocked,
|
||||
// The IPv6 address was expected to end with ']'
|
||||
// The IPv6 address was expected to end with "]"
|
||||
expected_close_bracket_in_address,
|
||||
// The torrent is being destructed, preventing the operation to
|
||||
// succeed
|
||||
|
@ -215,9 +215,9 @@ namespace libtorrent {
|
|||
sync_hash_not_found,
|
||||
// The encryption constant in the handshake is invalid
|
||||
invalid_encryption_constant,
|
||||
// The peer does not support plaintext, which is the selected mode
|
||||
// The peer does not support plain text, which is the selected mode
|
||||
no_plaintext_mode,
|
||||
// The peer does not support rc4, which is the selected mode
|
||||
// The peer does not support RC4, which is the selected mode
|
||||
no_rc4_mode,
|
||||
// The peer does not support any of the encryption modes that the
|
||||
// client supports
|
||||
|
@ -349,11 +349,11 @@ namespace libtorrent {
|
|||
#endif
|
||||
|
||||
|
||||
// The resume data file is missing the 'file sizes' entry
|
||||
// The resume data file is missing the ``file sizes`` entry
|
||||
missing_file_sizes = 130,
|
||||
// The resume data file 'file sizes' entry is empty
|
||||
// The resume data file ``file sizes`` entry is empty
|
||||
no_files_in_resume_data,
|
||||
// The resume data file is missing the 'pieces' and 'slots' entry
|
||||
// The resume data file is missing the ``pieces`` and ``slots`` entry
|
||||
missing_pieces,
|
||||
// The number of files in the resume data does not match the number
|
||||
// of files in the torrent
|
||||
|
@ -366,16 +366,16 @@ namespace libtorrent {
|
|||
mismatching_file_timestamp,
|
||||
// The resume data file is not a dictionary
|
||||
not_a_dictionary,
|
||||
// The 'blocks per piece' entry is invalid in the resume data file
|
||||
// The ``blocks per piece`` entry is invalid in the resume data file
|
||||
invalid_blocks_per_piece,
|
||||
// The resume file is missing the 'slots' entry, which is required
|
||||
// The resume file is missing the ``slots`` entry, which is required
|
||||
// for torrents with compact allocation. *DEPRECATED*
|
||||
missing_slots,
|
||||
// The resume file contains more slots than the torrent
|
||||
too_many_slots,
|
||||
// The 'slot' entry is invalid in the resume data
|
||||
// The ``slot`` entry is invalid in the resume data
|
||||
invalid_slot_list,
|
||||
// One index in the 'slot' list is invalid
|
||||
// One index in the ``slot`` list is invalid
|
||||
invalid_piece_index,
|
||||
// The pieces on disk needs to be re-ordered for the specified
|
||||
// allocation mode. This happens if you specify sparse allocation
|
||||
|
@ -416,17 +416,17 @@ namespace libtorrent {
|
|||
invalid_peer_dict,
|
||||
// tracker sent a failure message
|
||||
tracker_failure,
|
||||
// missing or invalid 'files' entry
|
||||
// missing or invalid ``files`` entry
|
||||
invalid_files_entry,
|
||||
// missing or invalid 'hash' entry
|
||||
// missing or invalid ``hash`` entry
|
||||
invalid_hash_entry,
|
||||
// missing or invalid 'peers' and 'peers6' entry
|
||||
// missing or invalid ``peers`` and ``peers6`` entry
|
||||
invalid_peers_entry,
|
||||
// udp tracker response packet has invalid size
|
||||
// UDP tracker response packet has invalid size
|
||||
invalid_tracker_response_length,
|
||||
// invalid transaction id in udp tracker response
|
||||
// invalid transaction id in UDP tracker response
|
||||
invalid_tracker_transaction_id,
|
||||
// invalid action field in udp tracker response
|
||||
// invalid action field in UDP tracker response
|
||||
invalid_tracker_action,
|
||||
|
||||
#if TORRENT_ABI_VERSION == 1
|
||||
|
|
|
@ -96,7 +96,9 @@ POSSIBILITY OF SUCH DAMAGE.
|
|||
// torrent has already been started and you want to hook in the extension at
|
||||
// run-time).
|
||||
//
|
||||
// The signature of the function is::
|
||||
// The signature of the function is:
|
||||
//
|
||||
// .. code:: c++
|
||||
//
|
||||
// std::shared_ptr<torrent_plugin> (*)(torrent_handle const&, void*);
|
||||
//
|
||||
|
|
|
@ -46,7 +46,7 @@ namespace libtorrent {
|
|||
|
||||
// constructor function for the ut_metadata extension. The ut_metadata
|
||||
// extension allows peers to request the .torrent file (or more
|
||||
// specifically the 'info'-dictionary of the .torrent file) from each
|
||||
// specifically the info-dictionary of the .torrent file) from each
|
||||
// other. This is the main building block in making magnet links work.
|
||||
// This extension is enabled by default unless explicitly disabled in
|
||||
// the session constructor.
|
||||
|
|
|
@ -128,6 +128,7 @@ namespace libtorrent {
|
|||
// open the file for reading and writing
|
||||
constexpr open_mode_t read_write = 1_bit;
|
||||
|
||||
// the mask for the bits making up the read-write mode.
|
||||
constexpr open_mode_t rw_mask = read_only | write_only | read_write;
|
||||
|
||||
// open the file in sparse mode (if supported by the
|
||||
|
|
|
@ -52,23 +52,23 @@ namespace libtorrent {
|
|||
// +----------+-----------------------+
|
||||
// | id chars | client |
|
||||
// +==========+=======================+
|
||||
// | 'LT' | libtorrent (default) |
|
||||
// | LT | libtorrent (default) |
|
||||
// +----------+-----------------------+
|
||||
// | 'UT' | uTorrent |
|
||||
// | UT | uTorrent |
|
||||
// +----------+-----------------------+
|
||||
// | 'UM' | uTorrent Mac |
|
||||
// | UM | uTorrent Mac |
|
||||
// +----------+-----------------------+
|
||||
// | 'qB' | qBittorrent |
|
||||
// | qB | qBittorrent |
|
||||
// +----------+-----------------------+
|
||||
// | 'BP' | BitTorrent Pro |
|
||||
// | BP | BitTorrent Pro |
|
||||
// +----------+-----------------------+
|
||||
// | 'BT' | BitTorrent |
|
||||
// | BT | BitTorrent |
|
||||
// +----------+-----------------------+
|
||||
// | 'DE' | Deluge |
|
||||
// | DE | Deluge |
|
||||
// +----------+-----------------------+
|
||||
// | 'AZ' | Azureus |
|
||||
// | AZ | Azureus |
|
||||
// +----------+-----------------------+
|
||||
// | 'TL' | Tribler |
|
||||
// | TL | Tribler |
|
||||
// +----------+-----------------------+
|
||||
//
|
||||
// There's an informal directory of client id's here_.
|
||||
|
|
|
@ -64,6 +64,7 @@ namespace libtorrent {
|
|||
struct http_connection;
|
||||
struct resolver_interface;
|
||||
|
||||
// internal
|
||||
constexpr int default_max_bottled_buffer_size = 2 * 1024 * 1024;
|
||||
|
||||
using http_handler = std::function<void(error_code const&
|
||||
|
|
|
@ -43,8 +43,15 @@ using announce_flags_t = flags::bitfield_flag<std::uint8_t, struct dht_announce_
|
|||
|
||||
namespace announce {
|
||||
|
||||
// announce to DHT as a seed
|
||||
constexpr announce_flags_t seed = 0_bit;
|
||||
|
||||
// announce to DHT with the implied-port flag set. This tells the network to use
|
||||
// your source UDP port as your listen port, rather than the one specified in
|
||||
// the message. This may improve the chances of traversing NATs when using uTP.
|
||||
constexpr announce_flags_t implied_port = 1_bit;
|
||||
|
||||
// Specify the port number for the SSL listen socket in the DHT announce.
|
||||
constexpr announce_flags_t ssl_torrent = 2_bit;
|
||||
|
||||
}
|
||||
|
|
|
@ -52,7 +52,6 @@ namespace libtorrent {
|
|||
constexpr int TORRENT_UDP_HEADER = 8;
|
||||
constexpr int TORRENT_UTP_HEADER = 20;
|
||||
constexpr int TORRENT_SOCKS5_HEADER = 6; // plus the size of the destination address
|
||||
|
||||
constexpr int TORRENT_ETHERNET_MTU = 1500;
|
||||
constexpr int TORRENT_TEREDO_MTU = 1280;
|
||||
constexpr int TORRENT_INET_MIN_MTU = 576;
|
||||
|
|
|
@ -51,8 +51,8 @@ namespace libtorrent {
|
|||
|
||||
struct TORRENT_EXTRA_EXPORT part_file
|
||||
{
|
||||
// create a part file at 'path', that can hold 'num_pieces' pieces.
|
||||
// each piece being 'piece_size' number of bytes
|
||||
// create a part file at ``path``, that can hold ``num_pieces`` pieces.
|
||||
// each piece being ``piece_size`` number of bytes
|
||||
part_file(std::string const& path, std::string const& name, int num_pieces, int piece_size);
|
||||
~part_file();
|
||||
|
||||
|
|
|
@ -41,11 +41,18 @@ namespace libtorrent {
|
|||
|
||||
using pex_flags_t = flags::bitfield_flag<std::uint8_t, struct pex_flags_tag>;
|
||||
|
||||
// these flags match the flags passed in ut_pex
|
||||
// messages
|
||||
// the peer supports protocol encryption
|
||||
constexpr pex_flags_t pex_encryption = 1_bit;
|
||||
|
||||
// the peer is a seed
|
||||
constexpr pex_flags_t pex_seed = 2_bit;
|
||||
|
||||
// the peer supports the uTP, transport protocol over UDP.
|
||||
constexpr pex_flags_t pex_utp = 3_bit;
|
||||
|
||||
// the peer supports the holepunch extension If this flag is received from a
|
||||
// peer, it can be used as a rendezvous point in case direct connections to
|
||||
// the peer fail
|
||||
constexpr pex_flags_t pex_holepunch = 4_bit;
|
||||
}
|
||||
|
||||
|
|
|
@ -468,6 +468,8 @@ namespace libtorrent {
|
|||
// Both these functions are exposed for advanced custom use of the DHT.
|
||||
// All torrents eligible to be announce to the DHT will be automatically,
|
||||
// by libtorrent.
|
||||
//
|
||||
// For possible flags, see announce_flags_t.
|
||||
void dht_get_peers(sha1_hash const& info_hash);
|
||||
void dht_announce(sha1_hash const& info_hash, int port = 0, dht::announce_flags_t flags = {});
|
||||
|
||||
|
|
|
@ -719,7 +719,7 @@ namespace aux {
|
|||
enable_dht,
|
||||
|
||||
// if the allowed encryption level is both, setting this to true will
|
||||
// prefer rc4 if both methods are offered, plain text otherwise
|
||||
// prefer RC4 if both methods are offered, plain text otherwise
|
||||
prefer_rc4,
|
||||
|
||||
// if true, hostname lookups are done via the configured proxy (if
|
||||
|
@ -1770,7 +1770,7 @@ namespace aux {
|
|||
{
|
||||
// use only plain text encryption
|
||||
pe_plaintext = 1,
|
||||
// use only rc4 encryption
|
||||
// use only RC4 encryption
|
||||
pe_rc4 = 2,
|
||||
// allow both
|
||||
pe_both = 3
|
||||
|
|
|
@ -90,7 +90,7 @@ namespace libtorrent {
|
|||
// before it's written to disk, and decrypting it when it's read again.
|
||||
//
|
||||
// The storage interface is based on pieces. Every read and write operation
|
||||
// happens in the piece-space. Each piece fits 'piece_size' number
|
||||
// happens in the piece-space. Each piece fits ``piece_size`` number
|
||||
// of bytes. All access is done by writing and reading whole or partial
|
||||
// pieces.
|
||||
//
|
||||
|
@ -156,6 +156,8 @@ namespace libtorrent {
|
|||
// The number of bytes read or written should be returned, or -1 on
|
||||
// error. If there's an error, the ``storage_error`` must be filled out
|
||||
// to represent the error that occurred.
|
||||
//
|
||||
// For possible values of ``flags``, see open_mode_t.
|
||||
virtual int readv(span<iovec_t const> bufs
|
||||
, piece_index_t piece, int offset, open_mode_t flags, storage_error& ec) = 0;
|
||||
virtual int writev(span<iovec_t const> bufs
|
||||
|
|
|
@ -135,7 +135,7 @@ namespace libtorrent {
|
|||
TORRENT_EXPORT storage_interface* disabled_storage_constructor(storage_params const&, file_pool&);
|
||||
|
||||
// the constructor function for the "zero" storage. This will always read
|
||||
// zeroes and ignore all writes.
|
||||
// zeros and ignore all writes.
|
||||
TORRENT_EXPORT storage_interface* zero_storage_constructor(storage_params const&, file_pool&);
|
||||
}
|
||||
|
||||
|
|
|
@ -118,8 +118,8 @@ namespace libtorrent {
|
|||
|
||||
// strdup is not part of the C standard. Some systems
|
||||
// don't have it and it won't be available when building
|
||||
// in strict ansi mode
|
||||
char* allocate_string_copy(string_view str);
|
||||
// in strict ANSI mode
|
||||
TORRENT_EXTRA_EXPORT char* allocate_string_copy(string_view str);
|
||||
|
||||
// searches for separator ('sep') in the string 'last'.
|
||||
// if found, returns the string_view representing the range from the start of
|
||||
|
|
|
@ -61,8 +61,8 @@ namespace torrent_flags {
|
|||
// Setting ``seed_mode`` on a torrent without metadata (a
|
||||
// .torrent file) is a no-op and will be ignored.
|
||||
//
|
||||
// It is not possible to *set* the `seed_mode` flag on a torrent after it has
|
||||
// been added to as session. It is possible to *clear* it though.
|
||||
// It is not possible to *set* the ``seed_mode`` flag on a torrent after it has
|
||||
// been added to a session. It is possible to *clear* it though.
|
||||
constexpr torrent_flags_t seed_mode = 0_bit;
|
||||
|
||||
// If ``upload_mode`` is set, the torrent will be initialized in
|
||||
|
@ -126,6 +126,10 @@ namespace torrent_flags {
|
|||
// order is the order the torrents were added. They are all downloaded
|
||||
// in that order. For more details, see queuing_.
|
||||
constexpr torrent_flags_t auto_managed = 5_bit;
|
||||
|
||||
// used in add_torrent_params to indicate that it's an error to attempt
|
||||
// to add a torrent that's already in the session. If it's not considered an
|
||||
// error, a handle to the existing torrent is returned.
|
||||
constexpr torrent_flags_t duplicate_is_error = 6_bit;
|
||||
|
||||
// on by default and means that this torrent will be part of state
|
||||
|
@ -185,7 +189,7 @@ namespace torrent_flags {
|
|||
// added to the list of trackers used by the torrent.
|
||||
// This flag is set by read_resume_data() if there are trackers present in
|
||||
// the resume data file. This effectively makes the trackers saved in the
|
||||
// resume data take presedence over the original trackers. This includes if
|
||||
// resume data take precedence over the original trackers. This includes if
|
||||
// there's an empty list of trackers, to support the case where they were
|
||||
// explicitly removed in the previous session.
|
||||
constexpr torrent_flags_t override_trackers = 11_bit;
|
||||
|
@ -196,7 +200,7 @@ namespace torrent_flags {
|
|||
// list of web seeds used by the torrent.
|
||||
// This flag is set by read_resume_data() if there are web seeds present in
|
||||
// the resume data file. This effectively makes the web seeds saved in the
|
||||
// resume data take presedence over the original ones. This includes if
|
||||
// resume data take precedence over the original ones. This includes if
|
||||
// there's an empty list of web seeds, to support the case where they were
|
||||
// explicitly removed in the previous session.
|
||||
constexpr torrent_flags_t override_web_seeds = 12_bit;
|
||||
|
@ -263,6 +267,8 @@ namespace torrent_flags {
|
|||
// set this flag to disable peer exchange for this torrent.
|
||||
constexpr torrent_flags_t disable_pex = 21_bit;
|
||||
|
||||
// all torrent flags combined. Can conveniently be used when creating masks
|
||||
// for flags
|
||||
constexpr torrent_flags_t all = torrent_flags_t::all();
|
||||
|
||||
// internal
|
||||
|
|
|
@ -727,8 +727,8 @@ namespace aux {
|
|||
// std::ofstream out((st.save_path
|
||||
// + "/" + st.name + ".fastresume").c_str()
|
||||
// , std::ios_base::binary);
|
||||
// out.unsetf(std::ios_base::skipws);
|
||||
// bencode(std::ostream_iterator<char>(out), *rd->resume_data);
|
||||
// std::vector<char> buf = write_resume_data_buf(rd->params);
|
||||
// out.write(buf.data(), buf.size());
|
||||
// --outstanding_resume_data;
|
||||
// }
|
||||
// }
|
||||
|
@ -993,7 +993,8 @@ namespace aux {
|
|||
// ``get_file_priorities()`` returns a vector with the priorities of all
|
||||
// files.
|
||||
//
|
||||
// The priority values are the same as for piece_priority().
|
||||
// The priority values are the same as for piece_priority(). See
|
||||
// download_priority_t.
|
||||
//
|
||||
// Whenever a file priority is changed, all other piece priorities are
|
||||
// reset to match the file priorities. In order to maintain special
|
||||
|
@ -1101,21 +1102,7 @@ namespace aux {
|
|||
// Typically this is one of the source flags in peer_info. i.e.
|
||||
// ``tracker``, ``pex``, ``dht`` etc.
|
||||
//
|
||||
// ``flags`` are the same flags that are passed along with the ``ut_pex`` extension.
|
||||
//
|
||||
// ==== ==========================================
|
||||
// 0x01 peer supports encryption.
|
||||
//
|
||||
// 0x02 peer is a seed
|
||||
//
|
||||
// 0x04 supports uTP. If this is not set, the peer will only be contacted
|
||||
// over TCP.
|
||||
//
|
||||
// 0x08 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
|
||||
// ==== ==========================================
|
||||
// For possible values of ``flags``, see pex_flags_t.
|
||||
void connect_peer(tcp::endpoint const& adr, peer_source_flags_t source = {}
|
||||
, pex_flags_t flags = pex_encryption | pex_utp | pex_holepunch) const;
|
||||
|
||||
|
@ -1252,7 +1239,9 @@ namespace aux {
|
|||
|
||||
// This function is intended only for use by plugins and the alert
|
||||
// dispatch function. This type does not have a stable API and should
|
||||
// be relied on as little as possible.
|
||||
// be relied on as little as possible. Accessing the handle returned by
|
||||
// this function is not thread safe outside of libtorrent's internal
|
||||
// thread (which is used to invoke plugin callbacks).
|
||||
std::shared_ptr<torrent> native_handle() const;
|
||||
|
||||
private:
|
||||
|
|
|
@ -123,7 +123,7 @@ TORRENT_VERSION_NAMESPACE_2
|
|||
// allocated.
|
||||
allocating,
|
||||
|
||||
// The torrent is currently checking the fastresume data and
|
||||
// The torrent is currently checking the fast resume 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.
|
||||
|
|
|
@ -69,7 +69,7 @@ namespace libtorrent {
|
|||
// The source IP address cannot be wild-carded, but
|
||||
// must be fully specified
|
||||
source_ip_cannot_be_wildcarded = 715,
|
||||
// The external port cannot be wildcarded, but must
|
||||
// The external port cannot be a wildcard, but must
|
||||
// be specified
|
||||
external_port_cannot_be_wildcarded = 716,
|
||||
// The port mapping entry specified conflicts with a
|
||||
|
|
|
@ -46,6 +46,7 @@ namespace libtorrent {
|
|||
|
||||
namespace utf8_errors
|
||||
{
|
||||
// internal
|
||||
enum error_code_enum
|
||||
{
|
||||
// conversion successful
|
||||
|
@ -54,7 +55,7 @@ namespace libtorrent {
|
|||
// partial character in source, but hit end
|
||||
source_exhausted,
|
||||
|
||||
// insuff. room in target for conversion
|
||||
// insufficient room in target for conversion
|
||||
target_exhausted,
|
||||
|
||||
// source sequence is illegal/malformed
|
||||
|
|
|
@ -543,7 +543,7 @@ TORRENT_TEST(piece_slots_seed_suggest_cache)
|
|||
}
|
||||
|
||||
// TODO: test what happens when loading a resume file with both piece priorities
|
||||
// and file priorities (file prio should take presedence)
|
||||
// and file priorities (file prio should take precedence)
|
||||
|
||||
// TODO: make sure a resume file only ever contain file priorities OR piece
|
||||
// priorities. Never both.
|
||||
|
|
Loading…
Reference in New Issue