automatically generate links in reference documentation for symbols (classes, enums, enum values, functions and member functions)
This commit is contained in:
Arvid Norberg
parent
4a4880a822
commit
3dcc7d5f8b
|
|
@ -158,7 +158,7 @@ def parse_function(lno, lines, filename):
|
|||
|
||||
lno = consume_block(lno - 1, lines)
|
||||
signature += ';'
|
||||
return [{ 'file': filename[11:], 'signatures': set([ signature ]), 'names': set([ signature.split('(')[0].split(' ')[-1].strip()])}, lno]
|
||||
return [{ 'file': filename[11:], 'signatures': set([ signature ]), 'names': set([ signature.split('(')[0].split(' ')[-1].strip() + '()'])}, lno]
|
||||
if len(signature) > 0:
|
||||
print '\x1b[31mFAILED TO PARSE FUNCTION\x1b[0m %s\nline: %d\nfile: %s' % (signature, lno, filename)
|
||||
return [None, lno]
|
||||
|
|
@ -510,6 +510,13 @@ for filename in files:
|
|||
context = ''
|
||||
h.close()
|
||||
|
||||
# ====================================================================
|
||||
#
|
||||
# RENDER PART
|
||||
#
|
||||
# ====================================================================
|
||||
|
||||
|
||||
if dump:
|
||||
|
||||
if verbose: print '\n===============================\n'
|
||||
|
|
@ -554,8 +561,17 @@ for c in classes:
|
|||
if c['file'] in overviews:
|
||||
categories[cat]['overview'] = overviews[c['file']]
|
||||
|
||||
filename = categories[cat]['filename'].replace('.rst', '.html') + '#'
|
||||
categories[cat]['classes'].append(c)
|
||||
symbols[c['name']] = categories[cat]['filename'].replace('.rst', '.html') + '#' + c['name']
|
||||
symbols[c['name']] = filename + c['name']
|
||||
for f in c['fun']:
|
||||
for n in f['names']:
|
||||
symbols[n] = filename + n
|
||||
|
||||
for e in c['enums']:
|
||||
symbols[e['name']] = filename + e['name']
|
||||
for v in e['values']:
|
||||
symbols[v['name']] = filename + v['name']
|
||||
|
||||
for f in functions:
|
||||
cat = categorize_symbol(first_item(f['names']), f['file'])
|
||||
|
|
@ -578,6 +594,39 @@ for e in enums:
|
|||
|
||||
def print_declared_in(out, o):
|
||||
out.write('Declared in "%s"\n\n' % print_link(o['file'], '../include/%s' % o['file']))
|
||||
print >>out, dump_link_targets()
|
||||
|
||||
# returns RST marked up string
|
||||
def linkify_symbols(string):
|
||||
lines = string.split('\n')
|
||||
abort = False
|
||||
ret = []
|
||||
for l in lines:
|
||||
if l.endswith('::'):
|
||||
abort = True
|
||||
if abort:
|
||||
ret.append(l)
|
||||
continue
|
||||
words = l.split(' ')
|
||||
for i in range(len(words)):
|
||||
# it's important to preserve leading
|
||||
# tabs, since that's relevant for
|
||||
# rst markup
|
||||
leading_tabs = 0
|
||||
while leading_tabs < len(words[i]) and words[i][leading_tabs] == '\t':
|
||||
leading_tabs += 1
|
||||
|
||||
# preserve commas and dots at the end
|
||||
w = words[i].strip()
|
||||
trailing = ''
|
||||
if len(w) > 0 and (w[-1] == '.' or w[-1] == ','):
|
||||
trailing = w[-1]
|
||||
w = w[:-1]
|
||||
|
||||
if w in symbols:
|
||||
words[i] = (leading_tabs * '\t') + print_link(words[i].strip(), symbols[w]) + trailing
|
||||
ret.append(' '.join(words))
|
||||
return '\n'.join(ret)
|
||||
|
||||
link_targets = []
|
||||
|
||||
|
|
@ -597,6 +646,38 @@ def dump_link_targets():
|
|||
def heading(string, c):
|
||||
return '\n' + string + '\n' + (c * len(string)) + '\n'
|
||||
|
||||
def render_enums(out, enums):
|
||||
for e in enums:
|
||||
print >>out, '.. raw:: html\n'
|
||||
print >>out, '\t<a name="%s"></a>' % e['name']
|
||||
print >>out, ''
|
||||
print >>out, heading('enum %s' % e['name'], '.')
|
||||
width = [len('name'), len('value'), len('description')]
|
||||
|
||||
for i in range(len(e['values'])):
|
||||
e['values'][i]['desc'] = linkify_symbols(e['values'][i]['desc'])
|
||||
|
||||
for v in e['values']:
|
||||
width[0] = max(width[0], len(v['name']))
|
||||
width[1] = max(width[1], len(v['val']))
|
||||
for d in v['desc'].split('\n'):
|
||||
width[2] = max(width[2], len(d))
|
||||
|
||||
print >>out, '+-' + ('-' * width[0]) + '-+-' + ('-' * width[1]) + '-+-' + ('-' * width[2]) + '-+'
|
||||
print >>out, '| ' + 'name'.ljust(width[0]) + ' | ' + 'value'.ljust(width[1]) + ' | ' + 'description'.ljust(width[2]) + ' |'
|
||||
print >>out, '+=' + ('=' * width[0]) + '=+=' + ('=' * width[1]) + '=+=' + ('=' * width[2]) + '=+'
|
||||
for v in e['values']:
|
||||
d = v['desc'].split('\n')
|
||||
if len(d) == 0: d = ['']
|
||||
print >>out, '| ' + v['name'].ljust(width[0]) + ' | ' + v['val'].ljust(width[1]) + ' | ' + d[0].ljust(width[2]) + ' |'
|
||||
for s in d[1:]:
|
||||
print >>out, '| ' + (' ' * width[0]) + ' | ' + (' ' * width[1]) + ' | ' + s.ljust(width[2]) + ' |'
|
||||
print >>out, '+-' + ('-' * width[0]) + '-+-' + ('-' * width[1]) + '-+-' + ('-' * width[2]) + '-+'
|
||||
print >>out, ''
|
||||
|
||||
print >>out, dump_link_targets()
|
||||
|
||||
|
||||
out = open('reference.rst', 'w+')
|
||||
out.write('''==================================
|
||||
libtorrent reference documentation
|
||||
|
|
@ -616,7 +697,7 @@ for cat in categories:
|
|||
print >>out, '| ' + print_link(c['name'], symbols[c['name']])
|
||||
for f in categories[cat]['functions']:
|
||||
for n in f['names']:
|
||||
print >>out, '| ' + print_link(n + '()', symbols[n])
|
||||
print >>out, '| ' + print_link(n, symbols[n])
|
||||
for e in categories[cat]['enums']:
|
||||
print >>out, '| ' + print_link(e['name'], symbols[e['name']])
|
||||
print >>out, ''
|
||||
|
|
@ -650,7 +731,11 @@ for cat in categories:
|
|||
|
||||
out.write('%s\n' % heading(c['name'], '-'))
|
||||
print_declared_in(out, c)
|
||||
out.write('%s\n\n.. parsed-literal::\n\t' % c['desc'])
|
||||
c['desc'] = linkify_symbols(c['desc'])
|
||||
out.write('%s\n' % c['desc'])
|
||||
print >>out, dump_link_targets()
|
||||
|
||||
print >>out,'\n.. parsed-literal::\n\t'
|
||||
|
||||
block = '\n%s\n{\n' % c['decl']
|
||||
for f in c['fun']:
|
||||
|
|
@ -687,7 +772,7 @@ for cat in categories:
|
|||
print >>out, '\t<a name="%s"></a>' % n
|
||||
print >>out, ''
|
||||
for n in f['names']:
|
||||
title += '%s() ' % n
|
||||
title += '%s ' % n
|
||||
print >>out, heading(title.strip(), '.')
|
||||
|
||||
block = '.. parsed-literal::\n\n'
|
||||
|
|
@ -695,31 +780,12 @@ for cat in categories:
|
|||
for s in f['signatures']:
|
||||
block += highlight_signature(s.replace('\n', '\n ')) + '\n'
|
||||
print >>out, '%s\n' % block.replace('\n', '\n\t')
|
||||
f['desc'] = linkify_symbols(f['desc'])
|
||||
print >>out, '%s' % f['desc']
|
||||
|
||||
print >>out, dump_link_targets()
|
||||
|
||||
for e in c['enums']:
|
||||
print >>out, '.. raw:: html\n'
|
||||
print >>out, '\t<a name="%s"></a>' % e['name']
|
||||
print >>out, ''
|
||||
print >>out, heading('enum %s' % e['name'], '.')
|
||||
width = [len('name'), len('value'), len('description')]
|
||||
for v in e['values']:
|
||||
width[0] = max(width[0], len(v['name']))
|
||||
width[1] = max(width[1], len(v['val']))
|
||||
for d in v['desc'].split('\n'):
|
||||
width[2] = max(width[2], len(d))
|
||||
|
||||
print >>out, '+-' + ('-' * width[0]) + '-+-' + ('-' * width[1]) + '-+-' + ('-' * width[2]) + '-+'
|
||||
print >>out, '| ' + 'name'.ljust(width[0]) + ' | ' + 'value'.ljust(width[1]) + ' | ' + 'description'.ljust(width[2]) + ' |'
|
||||
print >>out, '+=' + ('=' * width[0]) + '=+=' + ('=' * width[1]) + '=+=' + ('=' * width[2]) + '=+'
|
||||
for v in e['values']:
|
||||
d = v['desc'].split('\n')
|
||||
if len(d) == 0: d = ['']
|
||||
print >>out, '| ' + v['name'].ljust(width[0]) + ' | ' + v['val'].ljust(width[1]) + ' | ' + d[0].ljust(width[2]) + ' |'
|
||||
for s in d[1:]:
|
||||
print >>out, '| ' + (' ' * width[0]) + ' | ' + (' ' * width[1]) + ' | ' + s.ljust(width[2]) + ' |'
|
||||
print >>out, '+-' + ('-' * width[0]) + '-+-' + ('-' * width[1]) + '-+-' + ('-' * width[2]) + '-+'
|
||||
print >>out, ''
|
||||
render_enums(out, c['enums'])
|
||||
|
||||
for f in c['fields']:
|
||||
if f['desc'] == '': continue
|
||||
|
|
@ -732,8 +798,11 @@ for cat in categories:
|
|||
for n in f['names']:
|
||||
print >>out, '%s ' % n,
|
||||
print >>out, ''
|
||||
f['desc'] = linkify_symbols(f['desc'])
|
||||
print >>out, '\t%s' % f['desc'].replace('\n', '\n\t')
|
||||
|
||||
print >>out, dump_link_targets()
|
||||
|
||||
|
||||
for f in functions:
|
||||
h = ''
|
||||
|
|
@ -742,7 +811,7 @@ for cat in categories:
|
|||
print >>out, '\t<a name="%s"></a>' % n
|
||||
print >>out, ''
|
||||
for n in f['names']:
|
||||
h += '%s() ' % n
|
||||
h += '%s ' % n
|
||||
print >>out, heading(h, '.')
|
||||
print_declared_in(out, f)
|
||||
|
||||
|
|
@ -751,31 +820,11 @@ for cat in categories:
|
|||
block += highlight_signature(s) + '\n'
|
||||
|
||||
print >>out, '%s\n' % block.replace('\n', '\n\t')
|
||||
print >>out, f['desc']
|
||||
print >>out, linkify_symbols(f['desc'])
|
||||
|
||||
for e in enums:
|
||||
print >>out, '.. raw:: html\n'
|
||||
print >>out, '\t<a name="%s"></a>' % e['name']
|
||||
print >>out, ''
|
||||
print >>out, heading('enum %s' % e['name'], '.')
|
||||
width = [len('name'), len('value'), len('description')]
|
||||
for v in e['values']:
|
||||
width[0] = max(width[0], len(v['name']))
|
||||
width[1] = max(width[1], len(v['val']))
|
||||
for d in v['desc'].split('\n'):
|
||||
width[2] = max(width[2], len(d))
|
||||
|
||||
print >>out, '+-' + ('-' * width[0]) + '-+-' + ('-' * width[1]) + '-+-' + ('-' * width[2]) + '-+'
|
||||
print >>out, '| ' + 'name'.ljust(width[0]) + ' | ' + 'value'.ljust(width[1]) + ' | ' + 'description'.ljust(width[2]) + ' |'
|
||||
print >>out, '+=' + ('=' * width[0]) + '=+=' + ('=' * width[1]) + '=+=' + ('=' * width[2]) + '=+'
|
||||
for v in e['values']:
|
||||
d = v['desc'].split('\n')
|
||||
if len(d) == 0: d = ['']
|
||||
print >>out, '| ' + v['name'].ljust(width[0]) + ' | ' + v['val'].ljust(width[1]) + ' | ' + d[0].ljust(width[2]) + ' |'
|
||||
for s in d[1:]:
|
||||
print >>out, '| ' + (' ' * width[0]) + ' | ' + (' ' * width[1]) + ' | ' + s.ljust(width[2]) + ' |'
|
||||
print >>out, '+-' + ('-' * width[0]) + '-+-' + ('-' * width[1]) + '-+-' + ('-' * width[2]) + '-+'
|
||||
print >>out, ''
|
||||
print >>out, dump_link_targets()
|
||||
|
||||
render_enums(out, enums)
|
||||
|
||||
print >>out, dump_link_targets()
|
||||
|
||||
|
|
|
|||
|
|
@ -2,6 +2,22 @@
|
|||
|
||||
WEB_PATH = ~/Documents/rasterbar/web/products/libtorrent
|
||||
|
||||
REFERENCE_TARGETS = \
|
||||
reference \
|
||||
reference-Core \
|
||||
reference-String \
|
||||
reference-Plugins \
|
||||
reference-Create_Torrents \
|
||||
reference-Error_Codes \
|
||||
reference-Time \
|
||||
reference-Storage \
|
||||
reference-Custom_Storage \
|
||||
reference-Utility \
|
||||
reference-Bencoding \
|
||||
reference-Alerts \
|
||||
reference-RSS \
|
||||
reference-Filter
|
||||
|
||||
TARGETS = index \
|
||||
udp_tracker_protocol \
|
||||
dht_rss \
|
||||
|
|
@ -23,20 +39,7 @@ TARGETS = index \
|
|||
utp \
|
||||
tuning \
|
||||
hacking \
|
||||
reference \
|
||||
reference-Core \
|
||||
reference-String \
|
||||
reference-Plugins \
|
||||
reference-Create_Torrents \
|
||||
reference-Error_Codes \
|
||||
reference-Time \
|
||||
reference-Storage \
|
||||
reference-Custom_Storage \
|
||||
reference-Utility \
|
||||
reference-Bencoding \
|
||||
reference-Alerts \
|
||||
reference-RSS \
|
||||
reference-Filter
|
||||
$(REFERENCE_TARGETS)
|
||||
|
||||
FIGURES = read_disk_buffers write_disk_buffers troubleshooting
|
||||
|
||||
|
|
@ -51,7 +54,7 @@ all: html
|
|||
todo.html:gen_todo.py ../src/*.cpp ../include/libtorrent/*.hpp
|
||||
python gen_todo.py
|
||||
|
||||
reference.rst reference-Create_Torrents.rst reference-Error_Codes.rst reference-Plugins.rst reference-Core.rst reference-String.rst reference-Storage.rst:gen_reference_doc.py ../include/libtorrent/*.hpp
|
||||
$(REFERENCE_TARGETS:=.rst):gen_reference_doc.py ../include/libtorrent/*.hpp ../include/libtorrent/kademlia/*.hpp
|
||||
python gen_reference_doc.py
|
||||
|
||||
%.epub:%.rst
|
||||
|
|
|
|||
|
|
@ -244,7 +244,7 @@ namespace libtorrent
|
|||
|
||||
// The optional parameter, ``resume_data`` 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
|
||||
// `save_resume_data()`_ on `torrent_handle`_. See `fast resume`_. The ``vector`` that is
|
||||
// save_resume_data() on `torrent_handle`_. See `fast resume`_. The ``vector`` that is
|
||||
// passed in will be swapped into the running torrent instance with ``std::vector::swap()``.
|
||||
std::vector<char> resume_data;
|
||||
|
||||
|
|
@ -254,8 +254,8 @@ namespace libtorrent
|
|||
// 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 ``storage_interface``
|
||||
// that needs to be implemented for a custom storage, see `storage_interface`_.
|
||||
// content on disk for instance. For more information about the storage_interface
|
||||
// that needs to be implemented for a custom storage, see storage_interface.
|
||||
storage_constructor_type storage;
|
||||
|
||||
// The ``userdata`` parameter is optional and will be passed on to the extension
|
||||
|
|
@ -281,7 +281,7 @@ namespace libtorrent
|
|||
// true info-hash of the .torrent. Instead a placeholder, unique, info-hash is used
|
||||
// which is later updated once the .torrent file has been downloaded.
|
||||
//
|
||||
// Once the info-hash change happens, a torrent_update_alert_ is posted.
|
||||
// Once the info-hash change happens, a torrent_update_alert is posted.
|
||||
std::string url;
|
||||
|
||||
// if ``uuid`` is specified, it is used to find duplicates. If another torrent is already
|
||||
|
|
|
|||
|
|
@ -130,7 +130,7 @@ namespace libtorrent
|
|||
|
||||
// The ``integer()``, ``string()``, ``list()`` and ``dict()`` functions
|
||||
// are accessors that return the respective type. If the ``entry`` object isn't of the
|
||||
// type you request, the accessor will throw libtorrent_exception_ (which derives from
|
||||
// type you request, the accessor will throw libtorrent_exception (which derives from
|
||||
// ``std::runtime_error``). You can ask an ``entry`` for its type through the
|
||||
// ``type()`` function.
|
||||
//
|
||||
|
|
@ -167,7 +167,7 @@ namespace libtorrent
|
|||
// }
|
||||
//
|
||||
//
|
||||
// To make it easier to extract information from a torrent file, the class torrent_info_
|
||||
// To make it easier to extract information from a torrent file, the class torrent_info
|
||||
// exists.
|
||||
integer_type& integer();
|
||||
const integer_type& integer() const;
|
||||
|
|
|
|||
|
|
@ -83,16 +83,16 @@ namespace libtorrent
|
|||
|
||||
// By default ``auto_download`` is true, which means all torrents in
|
||||
// the feed will be downloaded. Set this to false in order to manually
|
||||
// add torrents to the session. You may react to the rss_alert_ when
|
||||
// add torrents to the session. You may react to the rss_alert when
|
||||
// a feed has been updated to poll it for the new items in the feed
|
||||
// when adding torrents manually. When torrents are added automatically,
|
||||
// an add_torrent_alert_ is posted which includes the torrent handle
|
||||
// an add_torrent_alert is posted which includes the torrent handle
|
||||
// as well as the error code if it failed to be added. You may also call
|
||||
// ``session::get_torrents()`` to get the handles to the new torrents.
|
||||
bool auto_download;
|
||||
|
||||
// ``auto_map_handles`` defaults to true and determines whether or
|
||||
// not to set the ``handle`` field in the ``feed_item``, returned
|
||||
// not to set the ``handle`` field in the feed_item, returned
|
||||
// as the feed status. If auto-download is enabled, this setting
|
||||
// is ignored. If auto-download is not set, setting this to false
|
||||
// will save one pass through all the feed items trying to find
|
||||
|
|
@ -110,7 +110,7 @@ namespace libtorrent
|
|||
// This object is used as a template for adding torrents from feeds,
|
||||
// but some torrent specific fields will be overridden by the
|
||||
// individual torrent being added. For more information on the
|
||||
// ``add_torrent_params``, see `async_add_torrent() add_torrent()`_.
|
||||
// add_torrent_params, see async_add_torrent() and add_torrent().
|
||||
add_torrent_params add_args;
|
||||
};
|
||||
|
||||
|
|
|
|||
|
|
@ -124,7 +124,7 @@ namespace libtorrent
|
|||
// If the fingerprint in the first overload is omited, the client will get a default
|
||||
// fingerprint stating the version of libtorrent. The fingerprint is a short string that will be
|
||||
// used in the peer-id to identify the client and the client's version. For more details see the
|
||||
// fingerprint_ class. The constructor that only takes a fingerprint will not open a
|
||||
// fingerprint class. The constructor that only takes a fingerprint will not open a
|
||||
// listen port for the session, to get it running you'll have to call ``session::listen_on()``.
|
||||
// The other constructor, that takes a port range and an interface as well as the fingerprint
|
||||
// will automatically try to listen on a port on the given interface. For more information about
|
||||
|
|
@ -196,8 +196,8 @@ namespace libtorrent
|
|||
// settings. ``save_state`` writes all keys to the ``entry`` that's passed in, which needs to
|
||||
// either not be initialized, or initialized as a dictionary.
|
||||
//
|
||||
// ``load_state`` expects a ``lazy_entry`` which can be built from a bencoded buffer with
|
||||
// `lazy_bdecode()`_.
|
||||
// ``load_state`` expects a lazy_entry which can be built from a bencoded buffer with
|
||||
// lazy_bdecode().
|
||||
//
|
||||
// The ``flags`` arguments passed in to ``save_state`` can be used to filter which parts
|
||||
// of the session state to save. By default, all state is saved (except for the individual
|
||||
|
|
@ -210,7 +210,7 @@ namespace libtorrent
|
|||
// with lots of torrents. If you're concerned about performance, consider
|
||||
// using ``post_torrent_updates()`` instead.
|
||||
//
|
||||
// ``get_torrent_status`` returns a vector of the ``torrent_status`` for every
|
||||
// ``get_torrent_status`` returns a vector of the torrent_status for every
|
||||
// torrent which satisfies ``pred``, 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 ``flags`` argument is the same
|
||||
|
|
@ -218,15 +218,15 @@ namespace libtorrent
|
|||
// every torrent, it may be used to count the number of torrents of different categories
|
||||
// as well.
|
||||
//
|
||||
// ``refresh_torrent_status`` takes a vector of ``torrent_status`` structs (for instance
|
||||
// the same vector that was returned by ``get_torrent_status()``) and refreshes the
|
||||
// ``refresh_torrent_status`` takes a vector of torrent_status structs (for instance
|
||||
// the same vector that was returned by get_torrent_status() ) and refreshes the
|
||||
// status based on the ``handle`` member. It is possible to use this function by
|
||||
// first setting up a vector of default constructed ``torrent_status`` objects, only
|
||||
// initializing the ``handle`` 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.
|
||||
//
|
||||
// Any ``torrent_status`` object whose ``handle`` member is not referring to a
|
||||
// Any torrent_status object whose ``handle`` member is not referring to a
|
||||
// valid torrent are ignored.
|
||||
void get_torrent_status(std::vector<torrent_status>* ret
|
||||
, boost::function<bool(torrent_status const&)> const& pred
|
||||
|
|
@ -234,7 +234,7 @@ namespace libtorrent
|
|||
void refresh_torrent_status(std::vector<torrent_status>* ret
|
||||
, boost::uint32_t flags = 0) const;
|
||||
|
||||
// This functions instructs the session to post the state_update_alert_, containing
|
||||
// This functions instructs the session to post the state_update_alert, containing
|
||||
// the status of all torrents whose state changed since the last time this function
|
||||
// was called.
|
||||
//
|
||||
|
|
@ -255,23 +255,23 @@ namespace libtorrent
|
|||
torrent_handle find_torrent(sha1_hash const& info_hash) const;
|
||||
std::vector<torrent_handle> get_torrents() const;
|
||||
|
||||
// You add torrents through the ``add_torrent()`` function where you give an
|
||||
// object with all the parameters. The ``add_torrent()`` overloads will block
|
||||
// You add torrents through the add_torrent() function where you give an
|
||||
// object with all the parameters. The add_torrent() overloads will block
|
||||
// until the torrent has been added (or failed to be added) and returns an
|
||||
// error code and a ``torrent_handle``. In order to add torrents more efficiently,
|
||||
// consider using ``async_add_torrent()`` which returns immediately, without
|
||||
// error code and a torrent_handle. In order to add torrents more efficiently,
|
||||
// consider using async_add_torrent() which returns immediately, without
|
||||
// waiting for the torrent to add. Notification of the torrent being added is sent
|
||||
// as add_torrent_alert_.
|
||||
// as add_torrent_alert.
|
||||
//
|
||||
// The overload that does not take an ``error_code`` throws an exception on
|
||||
// The overload that does not take an error_code throws an exception on
|
||||
// error and is not available when building without exception support.
|
||||
// The torrent_handle_ returned by ``add_torrent()`` can be used to retrieve information
|
||||
// The torrent_handle returned by add_torrent() can be used to retrieve information
|
||||
// about the torrent's progress, its peers etc. It is also used to abort a torrent.
|
||||
//
|
||||
// If the torrent you are trying to add already exists in the session (is either queued
|
||||
// for checking, being checked or downloading) ``add_torrent()`` will throw
|
||||
// libtorrent_exception_ which derives from ``std::exception`` unless ``duplicate_is_error``
|
||||
// is set to false. In that case, ``add_torrent`` will return the handle to the existing
|
||||
// libtorrent_exception which derives from ``std::exception`` unless duplicate_is_error
|
||||
// is set to false. In that case, add_torrent() will return the handle to the existing
|
||||
// torrent.
|
||||
//
|
||||
// all torrent_handles must be destructed before the session is destructed!
|
||||
|
|
@ -365,10 +365,10 @@ namespace libtorrent
|
|||
//
|
||||
// Before adding the feed, you must set the ``url`` field to the
|
||||
// feed's url. It may point to an RSS or an atom feed.
|
||||
// The returned feed_handle_ is a handle which is used to interact
|
||||
// The returned feed_handle is a handle which is used to interact
|
||||
// with the feed, things like forcing a refresh or querying for
|
||||
// information about the items in the feed. For more information,
|
||||
// see feed_handle_.
|
||||
// see feed_handle.
|
||||
feed_handle add_feed(feed_settings const& feed);
|
||||
|
||||
// Removes a feed from being watched by the session. When this
|
||||
|
|
@ -411,7 +411,7 @@ namespace libtorrent
|
|||
// client has its own source of bootstrapping nodes.
|
||||
//
|
||||
// ``set_dht_settings`` sets some parameters availavle to the dht node. See
|
||||
// dht_settings_ for more information.
|
||||
// dht_settings for more information.
|
||||
//
|
||||
// ``is_dht_running()`` returns true if the DHT support has been started and false
|
||||
// otherwise.
|
||||
|
|
@ -531,11 +531,11 @@ namespace libtorrent
|
|||
// 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 ip_filter_.
|
||||
// accepted and not, see ip_filter.
|
||||
//
|
||||
// Each time a peer is blocked because of the IP filter, a peer_blocked_alert_ is
|
||||
// Each time a peer is blocked because of the IP filter, a peer_blocked_alert is
|
||||
// generated.
|
||||
// ``get_ip_filter()`` Returns the ip_filter currently in the session. See ip_filter_.
|
||||
// ``get_ip_filter()`` Returns the ip_filter currently in the session. See ip_filter.
|
||||
void set_ip_filter(ip_filter const& f);
|
||||
ip_filter get_ip_filter() const;
|
||||
|
||||
|
|
@ -562,11 +562,11 @@ namespace libtorrent
|
|||
// of the interface you want the listener socket bound to. ``listen_on()`` returns the
|
||||
// error code of the operation in ``ec``. If this indicates success, the session is
|
||||
// listening on a port within the specified range. If it fails, it will also
|
||||
// generate an appropriate alert (listen_failed_alert_).
|
||||
// generate an appropriate alert (listen_failed_alert).
|
||||
//
|
||||
// If all ports in the specified range fails to be opened for listening, libtorrent will
|
||||
// try to use port 0 (which tells the operating system to pick a port that's free). If
|
||||
// that still fails you may see a listen_failed_alert_ with port 0 even if you didn't
|
||||
// that still fails you may see a listen_failed_alert with port 0 even if you didn't
|
||||
// ask to listen on it.
|
||||
//
|
||||
// It is possible to prevent libtorrent from binding to port 0 by passing in the flag
|
||||
|
|
@ -575,7 +575,7 @@ namespace libtorrent
|
|||
// The interface parameter can also be a hostname that will resolve to the device you
|
||||
// want to listen on. If you don't specify an interface, libtorrent may attempt to
|
||||
// listen on multiple interfaces (typically 0.0.0.0 and ::). This means that if your
|
||||
// IPv6 interface doesn't work, you may still see a listen_failed_alert_, even though
|
||||
// IPv6 interface doesn't work, you may still see a listen_failed_alert, even though
|
||||
// the IPv4 port succeeded.
|
||||
//
|
||||
// The ``flags`` parameter can either be 0 or ``session::listen_reuse_address``, which
|
||||
|
|
@ -656,12 +656,12 @@ namespace libtorrent
|
|||
// `options`` can be used to delete all the files downloaded by this torrent. To do this, pass
|
||||
// in the value ``session::delete_files``. The removal of the torrent is asyncronous, there is
|
||||
// no guarantee that adding the same torrent immediately after it was removed will not throw
|
||||
// a libtorrent_exception_ exception. Once the torrent is deleted, a torrent_deleted_alert_
|
||||
// a libtorrent_exception exception. Once the torrent is deleted, a torrent_deleted_alert
|
||||
// is posted.
|
||||
void remove_torrent(const torrent_handle& h, int options = none);
|
||||
|
||||
// Sets the session settings and the packet encryption settings respectively.
|
||||
// See session_settings_ and pe_settings_ for more information on available
|
||||
// See session_settings and pe_settings for more information on available
|
||||
// options.
|
||||
void set_settings(session_settings const& s);
|
||||
session_settings settings() const;
|
||||
|
|
@ -760,7 +760,7 @@ namespace libtorrent
|
|||
#endif
|
||||
|
||||
// ``pop_alert()`` is used to ask the session if any errors or events has occurred. With
|
||||
// `set_alert_mask()`_ you can filter which alerts to receive through ``pop_alert()``.
|
||||
// set_alert_mask() you can filter which alerts to receive through ``pop_alert()``.
|
||||
// For information about the alert categories, see alerts_.
|
||||
//
|
||||
// ``pop_alerts()`` pops all pending alerts in a single call. In high performance environments
|
||||
|
|
@ -793,7 +793,7 @@ namespace libtorrent
|
|||
// To control the max number of alerts that's queued by the session, see
|
||||
// ``session_settings::alert_queue_size``.
|
||||
//
|
||||
// ``save_resume_data_alert`` and ``save_resume_data_failed_alert`` are always posted, regardelss
|
||||
// save_resume_data_alert and save_resume_data_failed_alert are always posted, regardelss
|
||||
// of the alert mask.
|
||||
std::auto_ptr<alert> pop_alert();
|
||||
void pop_alerts(std::deque<alert*>* alerts);
|
||||
|
|
@ -837,7 +837,7 @@ namespace libtorrent
|
|||
//
|
||||
// The upnp object returned by ``start_upnp()`` can be used to add and remove
|
||||
// arbitrary port mappings. Mapping status is returned through the
|
||||
// portmap_alert_ and the portmap_error_alert_. The object will be valid until
|
||||
// portmap_alert and the portmap_error_alert. The object will be valid until
|
||||
// ``stop_upnp()`` is called. See `UPnP and NAT-PMP`_.
|
||||
//
|
||||
// It is off by default.
|
||||
|
|
@ -849,7 +849,7 @@ namespace libtorrent
|
|||
//
|
||||
// The natpmp object returned by ``start_natpmp()`` can be used to add and remove
|
||||
// arbitrary port mappings. Mapping status is returned through the
|
||||
// portmap_alert_ and the portmap_error_alert_. The object will be valid until
|
||||
// portmap_alert and the portmap_error_alert. The object will be valid until
|
||||
// ``stop_natpmp()`` is called. See `UPnP and NAT-PMP`_.
|
||||
//
|
||||
// It is off by default.
|
||||
|
|
|
|||
|
|
@ -294,7 +294,7 @@ namespace libtorrent
|
|||
//
|
||||
// The overloads that takes an ``error_code const&`` never throws if an error occur, they
|
||||
// will simply set the error code to describe what went wrong and not fully initialize the
|
||||
// torrent_info object. The overloads that do not take the extra error_code_ parameter will
|
||||
// torrent_info 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.
|
||||
//
|
||||
|
|
@ -330,17 +330,17 @@ namespace libtorrent
|
|||
|
||||
~torrent_info();
|
||||
|
||||
// The ``file_storage`` object contains the information on how to map the pieces to
|
||||
// files. It is separated from the ``torrent_info`` object because when creating torrents
|
||||
// The file_storage object contains the information on how to map the pieces to
|
||||
// files. It is separated from the torrent_info 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 ``file_storage`` in order
|
||||
// in a storage, the storage needs to make its own copy of the file_storage in order
|
||||
// to make its mapping differ from the one in the torrent file.
|
||||
//
|
||||
// ``orig_files()`` 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 chaged using ``torrent_info::rename_file()``.
|
||||
//
|
||||
// For more information on the ``file_storage`` object, see the separate document on how
|
||||
// For more information on the file_storage object, see the separate document on how
|
||||
// to create torrents.
|
||||
file_storage const& files() const { return m_files; }
|
||||
file_storage const& orig_files() const { return m_orig_files ? *m_orig_files : m_files; }
|
||||
|
|
@ -466,13 +466,13 @@ namespace libtorrent
|
|||
|
||||
// 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 file_slice_.
|
||||
// for that piece is supposed to be stored. See file_slice.
|
||||
std::vector<file_slice> map_block(int piece, size_type offset, int size) const
|
||||
{ return m_files.map_block(piece, offset, size); }
|
||||
|
||||
// This function will map a range in a specific file into a range in the torrent.
|
||||
// The ``file_offset`` parameter is the offset in the file, given in bytes, where
|
||||
// 0 is the start of the file. See peer_request_.
|
||||
// 0 is the start of the file. See peer_request.
|
||||
//
|
||||
// The input range is assumed to be valid within the torrent. ``file_offset``
|
||||
// + ``size`` is not allowed to be greater than the file size. ``file_index``
|
||||
|
|
|
|||
Loading…
Reference in New Issue