wornvirtue
/
premiere-libtorrent
forked from premiere/premiere-libtorrent
1
0
Fork 0
Code Pull Requests Activity

started moving some documentation into the headers

This commit is contained in:
Arvid Norberg 2013-07-20 20:11:01 +00:00
parent dfc292ebda
commit a832c5e3c4
4 changed files with 308 additions and 477 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
docs/gen_reference_doc.py
View File

@ -130,7 +130,7 @@ def parse_function(lno, lines, filename):
lno = consume_block(lno - 1, lines)
signature += ';'
return [{ 'file': filename[11:], 'signature': signature, 'name': signature.split('(')[0].split(' ')[-1].strip()}, lno]
return [{ 'file': filename[11:], 'overloads': [{'signature': signature, 'name': 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]
@ -146,6 +146,7 @@ def parse_class(lno, lines, filename):
state = 'public'
context = ''
class_type = 'struct'
blanks = 0
while lno < len(lines):
l = lines[lno].strip()
@ -162,6 +163,10 @@ def parse_class(lno, lines, filename):
l = lines[lno].strip()
lno += 1
if l == '':
blanks += 1
continue
if l.startswith('/*'):
lno = consume_comment(lno - 1, lines)
continue
@ -172,9 +177,11 @@ def parse_class(lno, lines, filename):
if 'TORRENT_DEFINE_ALERT' in l:
if verbose: print 'xx %s' % l
blanks += 1
continue
if 'TORRENT_DEPRECATED' in l:
if verbose: print 'xx %s' % l
blanks += 1
continue
if l.startswith('//'):
@ -195,18 +202,24 @@ def parse_class(lno, lines, filename):
if state != 'public' and not internal:
if verbose: print 'private %s' % l
blanks += 1
continue
if start_brace - end_brace > 1:
if verbose: print 'scope %s' % l
blanks += 1
continue;
if looks_like_function(l):
current_fun, lno = parse_function(lno - 1, lines, filename)
if current_fun != None:
current_fun['desc'] = context
funs.append(current_fun)
if context == '' and blanks == 0 and len(funs):
funs[-1]['overloads'] += current_fun['overloads']
else:
current_fun['desc'] = context
funs.append(current_fun)
context = ''
blanks = 0
continue
if looks_like_variable(l):
@ -268,7 +281,7 @@ def parse_enum(lno, lines, filename):
l = l.split('}')[0]
if len(l):
if verbose: print 'enum %s' % lines[lno-1]
if verbose: print 'enumv %s' % lines[lno-1]
for v in l.split(','):
if v == '': continue
values.append({'name': v.strip(), 'desc': context})
@ -338,11 +351,16 @@ for filename in files:
if verbose: print '\n=== %s ===\n' % filename
blanks = 0
lno = 0
while lno < len(lines):
l = lines[lno].strip()
lno += 1
if l == '':
blanks += 1
continue
if l.startswith('//'):
if verbose: print 'desc %s' % l
l = l.split('//')[1]
@ -358,9 +376,11 @@ for filename in files:
continue
if 'TORRENT_CFG' in l:
blanks += 1
if verbose: print 'xx %s' % l
continue
if 'TORRENT_DEPRECATED' in l:
blanks += 1
if verbose: print 'xx %s' % l
continue
@ -371,19 +391,25 @@ for filename in files:
current_class['desc'] = context
classes.append(current_class)
context = ''
blanks += 1
continue
if looks_like_function(l):
current_fun, lno = parse_function(lno - 1, lines, filename)
if current_fun != None:
current_fun['desc'] = context
functions.append(current_fun)
if context == '' and blanks == 0 and len(functions):
functions[-1]['overloads'] += current_fun['overloads']
else:
current_fun['desc'] = context
functions.append(current_fun)
blanks = 0
context = ''
continue
if ('class ' in l or 'struct ' in l) and not ';' in l:
lno = consume_block(lno - 1, lines)
context = ''
blanks += 1
continue
if l.startswith('enum '):
@ -392,8 +418,10 @@ for filename in files:
current_enum['desc'] = context
enums.append(current_enum)
context = ''
blanks += 1
continue
blanks += 1
if verbose: print '?? %s' % l
context = ''
@ -406,7 +434,8 @@ if dump:
for c in classes:
print '\x1b[4m%s\x1b[0m %s\n{' % (c['type'], c['name'])
for f in c['fun']:
print ' %s' % f['signature'].replace('\n', '\n ')
for o in f['overloads']:
print ' %s' % o['signature'].replace('\n', '\n ')
if len(c['fun']) > 0 and len(c['fields']) > 0: print ''
@ -441,11 +470,12 @@ for c in classes:
symbols[c['name']] = categories[cat]['filename'] + '#' + html_sanitize(c['name'])
for f in functions:
cat = categorize_symbol(f['name'], f['file'])
cat = categorize_symbol(f['overloads'][0]['name'], f['file'])
if not cat in categories:
categories[cat] = { 'classes': [], 'functions': [], 'enums': [], 'filename': 'reference-%s.html' % cat.replace(' ', '_')}
for o in f['overloads']:
symbols[o['name']] = categories[cat]['filename'] + '#' + html_sanitize(o['name'])
categories[cat]['functions'].append(f)
symbols[f['name']] = categories[cat]['filename'] + '#' + html_sanitize(f['name'])
for e in enums:
cat = categorize_symbol(e['name'], e['file'])
@ -475,7 +505,8 @@ for cat in categories:
for c in categories[cat]['classes']:
print >>out, '<a href="%s#%s">%s %s</a><br/>' % (category_filename, html_sanitize(c['name']), html_sanitize(c['type']), html_sanitize(c['name']))
for f in categories[cat]['functions']:
print >>out, '<a href="%s#%s">%s()</a><br/>' % (category_filename, html_sanitize(f['name']), html_sanitize(f['name']))
name = html_sanitize(f['overloads'][0]['name'])
print >>out, '<a href="%s#%s">%s()</a><br/>' % (category_filename, name, name)
for e in categories[cat]['enums']:
print >>out, '<a href="%s#%s">enum %s</a><br/>' % (category_filename, html_sanitize(e['name']), html_sanitize(e['name']))
print >>out, '</p>'
@ -504,7 +535,9 @@ for cat in categories:
out.write('<pre class="literal-block">')
print >>out, '%s\n{' % html_sanitize(c['decl'])
for f in c['fun']:
print >>out, ' %s' % html_sanitize(f['signature'].replace('\n', '\n ')).replace(f['name'], '<strong>' + f['name'] + '</strong>')
for o in f['overloads']:
name = html_sanitize(o['name'])
print >>out, ' %s' % html_sanitize(o['signature'].replace('\n', '\n ')).replace(name, '<strong>' + name + '</strong>')
if len(c['fun']) > 0 and len(c['enums']) + len(c['fields']) > 0: print >>out, ''
@ -525,12 +558,21 @@ for cat in categories:
out.write('};</pre>')
# TODO: merge overloaded functions
for f in c['fun']:
if f['desc'] == '': continue
name = html_sanitize(f['name'])
print >>out, '<a name="%s"></a><h3>%s()</h3>' % (name, name)
print >>out, '<blockquote><pre class="literal-block">%s</pre></blockquote>' % html_sanitize(f['signature'].replace('\n', '\n ')).replace(name, '<strong>' + name + '</strong>')
for o in f['overloads']:
name = html_sanitize(o['name'])
print >>out, '<a name="%s"></a>' % name
print >>out, '<h3>'
for o in f['overloads']:
name = html_sanitize(o['name'])
print >>out, '%s() ' % name
print >>out, '</h3>'
print >>out, '<blockquote><pre class="literal-block">'
for o in f['overloads']:
name = html_sanitize(o['name'])
print >>out, html_sanitize(o['signature'].replace('\n', '\n ')).replace(name, '<strong>' + name + '</strong>')
print >>out, '</pre></blockquote>'
print >>out, '<p>%s</p>' % html_sanitize(f['desc'])
for e in c['enums']:
@ -547,12 +589,21 @@ for cat in categories:
print >>out, '<dd>%s</dd>' % html_sanitize(f['desc'])
# TODO: merge overloaded functions
for f in functions:
name = html_sanitize(f['name'])
print >>out, '<a name="%s"></a><h2>%s()</h2>' % (name, name)
for o in f['overloads']:
name = html_sanitize(o['name'])
print >>out, '<a name="%s"></a>' % name
print >>out, '<h2>'
for o in f['overloads']:
name = html_sanitize(o['name'])
print >>out, '%s() ' % name
print >>out, '</h2>'
print_declared_in(out, f)
print >>out, '<blockquote><pre class="literal-block">%s</pre></blockquote>' % html_sanitize(f['signature']).replace(name, '<strong>' + name + '</strong>')
print >>out, '<blockquote><pre class="literal-block">'
for o in f['overloads']:
name = html_sanitize(o['name'])
print >>out, html_sanitize(o['signature']).replace(name, '<strong>' + name + '</strong>')
print >>out, '</pre></blockquote>'
print >>out, '<p>%s</p>' % html_sanitize(f['desc'])
for e in enums:
@ -561,7 +612,7 @@ for cat in categories:
print_declared_in(out, e)
print >>out, '<table><tr><th>value</th><th>description</th></tr>'
for v in e['values']:
print >>out, '<tr><td>%s</td><td>%s</td></tr>' % (name, html_sanitize(v['desc']))
print >>out, '<tr><td>%s</td><td>%s</td></tr>' % (html_sanitize(v['name']), html_sanitize(v['desc']))
print >>out, '</table>'
out.write('</body></html>')

453
docs/manual.rst
View File

@ -93,268 +93,6 @@ For documentation on these types, please refer to the `asio documentation`_.
.. _`asio documentation`: http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html
session
=======
The ``session`` class has the following synopsis::
class session: public boost::noncopyable
{
session(fingerprint const& print
= libtorrent::fingerprint(
"LT", 0, 1, 0, 0)
, int flags = start_default_features
| add_default_plugins
, int alert_mask = alert::error_notification);
session(
fingerprint const& print
, std::pair<int, int> listen_port_range
, char const* listen_interface = 0
, int flags = start_default_features
| add_default_plugins
, int alert_mask = alert::error_notification);
enum save_state_flags_t
{
save_settings = 0x001,
save_dht_settings = 0x002,
save_dht_state = 0x004,
save_proxy = 0x008,
save_i2p_proxy = 0x010,
save_encryption_settings = 0x020,
save_as_map = 0x040,
save_feeds = 0x080,
};
void load_state(lazy_entry const& e);
void save_state(entry& e, boost::uint32_t flags) const;
torrent_handle add_torrent(
add_torrent_params const& params);
torrent_handle add_torrent(
add_torrent_params const& params
, error_code& ec);
void async_add_torrent(add_torrent_params const& params);
void pause();
void resume();
session_proxy abort();
enum options_t
{
none = 0,
delete_files = 1
};
enum session_flags_t
{
add_default_plugins = 1,
start_default_features = 2
};
void remove_torrent(torrent_handle const& h
, int options = none);
torrent_handle find_torrent(sha_hash const& ih);
std::vector<torrent_handle> get_torrents() const;
void get_torrent_status(std::vector<torrent_status>* ret
, boost::function<bool(torrent_status const&)> const& pred
, boost::uint32_t flags = 0) const;
void refresh_torrent_status(std::vector<torrent_status>* ret
, boost::uint32_t flags) const;
void set_settings(session_settings const& settings);
session_settings settings() const;
void set_pe_settings(pe_settings const& settings);
void set_proxy(proxy_settings const& s);
proxy_settings proxy() const;
int num_uploads() const;
int num_connections() const;
void load_asnum_db(char const* file);
void load_asnum_db(wchar_t const* file);
void load_country_db(char const* file);
void load_country_db(wchar_t const* file);
int as_for_ip(address const& adr);
void set_ip_filter(ip_filter const& f);
ip_filter get_ip_filter() const;
session_status status() const;
cache_status get_cache_status() const;
bool is_listening() const;
unsigned short listen_port() const;
enum {
listen_reuse_address = 1,
listen_no_system_port = 2
};
void listen_on(
std::pair<int, int> const& port_range
, error_code& ec
, char const* interface = 0
, int flags = 0);
std::auto_ptr<alert> pop_alert();
alert const* wait_for_alert(time_duration max_wait);
void set_alert_mask(int m);
size_t set_alert_queue_size_limit(
size_t queue_size_limit_);
void set_alert_dispatch(boost::function<void(std::auto_ptr<alert>)> const& fun);
feed_handle add_feed(feed_settings const& feed);
void remove_feed(feed_handle h);
void get_feeds(std::vector<feed_handle>& f) const;
void add_extension(boost::function<
boost::shared_ptr<torrent_plugin>(torrent*)> ext);
void start_dht();
void stop_dht();
void set_dht_settings(
dht_settings const& settings);
entry dht_state() const;
void add_dht_node(std::pair<std::string
, int> const& node);
void add_dht_router(std::pair<std::string
, int> const& node);
bool is_dht_running() const;
void start_lsd();
void stop_lsd();
upnp* start_upnp();
void stop_upnp();
natpmp* start_natpmp();
void stop_natpmp();
};
Once it's created, the session 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.
session()
---------
::
session(fingerprint const& print
= libtorrent::fingerprint("LT", 0, 1, 0, 0)
, int flags = start_default_features
| add_default_plugins
, int alert_mask = alert::error_notification);
session(fingerprint const& print
, std::pair<int, int> listen_port_range
, char const* listen_interface = 0
, int flags = start_default_features
| add_default_plugins
, int alert_mask = alert::error_notification);
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
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
the parameters, see ``listen_on()`` function.
The flags paramater can be used to start default features (upnp & nat-pmp) and default plugins
(ut_metadata, ut_pex and smart_ban). The default is to start those things. If you do not want
them to start, pass 0 as the flags parameter.
The ``alert_mask`` is the same mask that you would send to `set_alert_mask()`_.
~session()
----------
The destructor of session 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 session
returns. So, it's advised that any kind of interface (such as windows) are closed before
destructing the session object. Because it can take a few second for it to finish. The
timeout can be set with ``set_settings()``.
load_state() save_state()
-------------------------
::
void load_state(lazy_entry const& e);
void save_state(entry& e, boost::uint32_t flags) const;
loads and saves all session settings, including dht_settings, encryption settings and proxy
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()`_.
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
torrents). These are the possible flags. A flag that's set, means those settings are saved::
enum save_state_flags_t
{
save_settings = 0x001,
save_dht_settings = 0x002,
save_dht_state = 0x004,
save_proxy = 0x008,
save_i2p_proxy = 0x010,
save_encryption_settings = 0x020,
save_as_map = 0x040,
save_feeds = 0x080
};
pause() resume() is_paused()
----------------------------
::
void pause();
void resume();
bool is_paused() const;
Pausing the session 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 session pause state is separate from
the torrent pause state. A torrent is inactive if it is paused or if the session is
paused.
abort()
-------
::
session_proxy abort();
In case you want to destruct the session asynchrounously, you can request a session
destruction proxy. If you don't do this, the destructor of the session object will
block while the trackers are contacted. If you keep one ``session_proxy`` to the
session when destructing it, the destructor will not block, but start to close down
the session, the destructor of the proxy will then synchronize the threads. So, the
destruction of the session is performed from the ``session`` destructor call until the
``session_proxy`` destructor call. The ``session_proxy`` does not have any operations
on it (since the session is being closed down, no operations are allowed on it). The
only valid operation is calling the destructor::
class session_proxy
{
public:
session_proxy();
~session_proxy()
};
async_add_torrent() add_torrent()
---------------------------------
@ -415,58 +153,6 @@ async_add_torrent() add_torrent()
, error_code& ec);
void async_add_torrent(add_torrent_params const& params);
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
waiting for the torrent to add. Notification of the torrent being added is sent
as add_torrent_alert_.
The overload that does not take an ``error_code`` throws an exception on
error and is not available when building without exception support.
The only mandatory parameters are ``save_path`` which is the directory where you
want the files to be saved. You also need to specify either the ``ti`` (the
torrent file), the ``info_hash`` (the info hash of the torrent) or the ``url``
(the URL to where to download the .torrent file from). If you 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 (``TORRENT_DISABLE_EXTENSIONS`` must not be
defined). It also takes an optional ``name`` 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 ``torrent_handle::name``.
If the torrent doesn't have a tracker, but relies on the DHT to find peers, the
``trackers`` (or the deprecated ``tracker_url``) can specify tracker urls that
for the torrent.
If you specify a ``url``, the torrent will be set in ``downloading_metadata`` 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 (``torrent_status::error``)
will indicate what went wrong. The ``url`` may refer to a magnet link or a regular
http URL.
If it refers to an HTTP URL, the info-hash for the added torrent will not be the
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.
``dht_nodes`` is a list of hostname and port pairs, representing DHT nodes to be
added to the session (if DHT is enabled). The hostname may be an IP address.
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
torrent.
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
passed in will be swapped into the running torrent instance with ``std::vector::swap()``.
The ``storage_mode`` parameter refers to the layout of the storage for this torrent.
There are 3 different modes:
@ -487,145 +173,6 @@ storage_mode_compact
For more information, see `storage allocation`_.
``storage`` 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`_.
The ``userdata`` parameter is optional and will be passed on to the extension
constructor functions, if any (see `add_extension()`_).
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.
``file_priorities`` can be set to control the initial file priorities when adding
a torrent. The semantics are the same as for ``torrent_handle::prioritize_files()``.
``version`` is filled in by the constructor and should be left untouched. It
is used for forward binary compatibility.
``trackerid`` is 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.
if ``uuid`` 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.
``source_feed_url`` should point to the URL of the RSS feed this torrent comes from,
if it comes from an RSS feed.
``flags`` is a 64 bit integer used for flags controlling aspects of this torrent
and how it's added. These are the flags::
enum flags_t
{
flag_seed_mode = 0x001,
flag_override_resume_data = 0x002,
flag_upload_mode = 0x004,
flag_share_mode = 0x008,
flag_apply_ip_filter = 0x010,
flag_paused = 0x020,
flag_auto_managed = 0x040.
flag_duplicate_is_error = 0x080,
flag_merge_resume_trackers = 0x100,
flag_update_subscribe = 0x200,
flag_super_seeding = 0x400,
flag_sequential_download = 0x800
}
``flag_apply_ip_filter`` 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 excempt for some reason, being
an auto-update torrent for instance.
``flag_merge_resume_trackers`` 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.
``flag_update_subscribe`` is on by default and means that this torrent will be part of state
updates when calling `post_torrent_updates()`_.
``flag_paused`` 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.
If you pass in resume data, the paused state of the torrent when the resume data
was saved will override the paused state you pass in here. You can override this
by setting ``flag_override_resume_data``.
If the torrent is auto-managed (``flag_auto_managed``), 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.
If ``flag_auto_managed`` 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 queuing_.
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 ``override_resume_data``.
If ``flag_seed_mode`` 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.
Setting ``flag_seed_mode`` on a torrent without metadata (a .torrent file) is a no-op
and will be ignored.
If resume data is passed in with this torrent, the seed mode saved in there will
override the seed mode you set here.
If ``flag_override_resume_data`` is set, the ``paused`` and ``auto_managed``
state of the torrent are not loaded from the resume data, but the states requested
by the flags in ``add_torrent_params`` will override them.
If ``flag_upload_mode`` 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.
If the torrent is auto-managed (``flag_auto_managed``), 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.
``flag_share_mode`` determines if the torrent should be added in *share mode* or not.
Share mode indicates that we are not interested in downloading the torrent, but
merley 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.
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 "100% finished" most of the time. Do not change file or piece
priorities for torrents in share mode, it will make it not work.
The share mode has one setting, the share ratio target, see ``session_settings::share_mode_target``
for more info.
``flag_super_seeding`` 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
``torrent_handle::super_seeding(true)`` on the torrent handle immediately
after adding it.
``flag_sequential_download`` sets the sequential download state for the torrent.
It has the same effect as calling ``torrent_handle::sequential_download(true)``
on the torrent handle immediately after adding it.
``max_uploads``, ``max_connections``, ``upload_limit``, ``download_limit`` correspond
to the ``set_max_uploads()``, ``set_max_connections()``, ``set_upload_limit()`` and
``set_download_limit()`` functions on torrent_handle_. These values let you initialize
these settings when the torrent is added, instead of calling these functions immediately
following adding it.
remove_torrent()
----------------

165
include/libtorrent/add_torrent_params.hpp
View File

@ -45,8 +45,29 @@ namespace libtorrent
{
class torrent_info;
// The add_torrent_params is a parameter pack for adding torrents to a session.
// The key fields when adding a torrent are:
//
// * ti - when you have a .torrent file
// * url - when you have a magnet link or http URL to the .torrent file
// * info_hash - when all you have is an info-hash (this is similar to a magnet link)
//
// one of those fields need to be set. Another mandatory field is ``save_path``.
// The add_torrent_params object is passed into one of the ``session::add_torrent()``
// overloads or ``session::async_add_torrent()``.
//
// 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 (``TORRENT_DISABLE_EXTENSIONS`` must not be
// defined). It also takes an optional ``name`` 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 ``torrent_handle::name``.
//
struct TORRENT_EXPORT add_torrent_params
{
// 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 ``storage`` field.
add_torrent_params(storage_constructor_type sc = default_storage_constructor)
: version(LIBTORRENT_VERSION_NUM)
#ifndef TORRENT_NO_DEPRECATE
@ -95,19 +116,105 @@ namespace libtorrent
}
#endif
// values for the ``flags`` field
enum flags_t
{
// If ``flag_seed_mode`` 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.
//
// Setting ``flag_seed_mode`` on a torrent without metadata (a .torrent file) is a no-op
// and will be ignored.
//
// If resume data is passed in with this torrent, the seed mode saved in there will
// override the seed mode you set here.
flag_seed_mode = 0x001,
// If ``flag_override_resume_data`` is set, the ``paused`` and ``auto_managed``
// state of the torrent are not loaded from the resume data, but the states requested
// by the flags in ``add_torrent_params`` will override them.
//
// If you pass in resume data, the paused state of the torrent when the resume data
// was saved will override the paused state you pass in here. You can override this
// by setting ``flag_override_resume_data``.
flag_override_resume_data = 0x002,
// If ``flag_upload_mode`` 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.
//
// If the torrent is auto-managed (``flag_auto_managed``), 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.
flag_upload_mode = 0x004,
// determines if the torrent should be added in *share mode* or not.
// Share mode indicates that we are not interested in downloading the torrent, but
// merley 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.
//
// 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 "100% finished" most of the time. Do not change file or piece
// priorities for torrents in share mode, it will make it not work.
//
// The share mode has one setting, the share ratio target, see ``session_settings::share_mode_target``
// for more info.
flag_share_mode = 0x008,
// 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 excempt for some reason, being
// an auto-update torrent for instance.
flag_apply_ip_filter = 0x010,
// ``flag_paused`` 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.
flag_paused = 0x020,
// If the torrent is auto-managed (``flag_auto_managed``), 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.
//
// If ``flag_auto_managed`` 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 queuing_.
//
// 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 ``override_resume_data``.
flag_auto_managed = 0x040,
flag_duplicate_is_error = 0x080,
// 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.
flag_merge_resume_trackers = 0x100,
// on by default and means that this torrent will be part of state
// updates when calling `post_torrent_updates()`_.
flag_update_subscribe = 0x200,
// 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
// ``torrent_handle::super_seeding(true)`` on the torrent handle immediately
// after adding it.
flag_super_seeding = 0x400,
// sets the sequential download state for the torrent.
// It has the same effect as calling ``torrent_handle::sequential_download(true)``
// on the torrent handle immediately after adding it.
flag_sequential_download = 0x800,
default_flags = flag_update_subscribe | flag_auto_managed | flag_paused | flag_apply_ip_filter
@ -116,27 +223,76 @@ namespace libtorrent
#endif
};
// libtorrent version. Used for forward binary compatibility
// ``version`` is filled in by the constructor and should be left untouched. It
// is used for forward binary compatibility.
int version;
boost::intrusive_ptr<torrent_info> ti;
#ifndef TORRENT_NO_DEPRECATE
char const* tracker_url;
#endif
// If the torrent doesn't have a tracker, but relies on the DHT to find peers, the
// ``trackers`` can specify tracker URLs for the torrent.
std::vector<std::string> trackers;
// ``dht_nodes`` is a list of hostname and port pairs, representing DHT nodes to be
// added to the session (if DHT is enabled). The hostname may be an IP address.
std::vector<std::pair<std::string, int> > dht_nodes;
sha1_hash info_hash;
std::string name;
std::string save_path;
// 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
// passed in will be swapped into the running torrent instance with ``std::vector::swap()``.
std::vector<char> resume_data;
storage_mode_t storage_mode;
// ``storage`` 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`_.
storage_constructor_type storage;
// The ``userdata`` parameter is optional and will be passed on to the extension
// constructor functions, if any (see `add_extension()`_).
void* userdata;
// ``file_priorities`` can be set to control the initial file priorities when adding
// a torrent. The semantics are the same as for ``torrent_handle::prioritize_files()``.
std::vector<boost::uint8_t> file_priorities;
// ``trackerid`` is 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.
std::string trackerid;
// If you specify a ``url``, the torrent will be set in ``downloading_metadata`` 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 (``torrent_status::error``)
// will indicate what went wrong. The ``url`` may refer to a magnet link or a regular
// http URL.
//
// If it refers to an HTTP URL, the info-hash for the added torrent will not be the
// 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.
std::string url;
// if ``uuid`` 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.
std::string uuid;
// ``source_feed_url`` should point to the URL of the RSS feed this torrent comes from,
// if it comes from an RSS feed.
std::string source_feed_url;
// flags controlling aspects of this torrent and how it's added. See flags_t for details.
boost::uint64_t flags;
#ifndef TORRENT_NO_DEPRECATE
bool seed_mode;
bool override_resume_data;
@ -148,6 +304,13 @@ namespace libtorrent
bool duplicate_is_error;
bool merge_resume_trackers;
#endif
// ``max_uploads``, ``max_connections``, ``upload_limit``, ``download_limit`` correspond
// to the ``set_max_uploads()``, ``set_max_connections()``, ``set_upload_limit()`` and
// ``set_download_limit()`` functions on torrent_handle_. These values let you initialize
// these settings when the torrent is added, instead of calling these functions immediately
// following adding it.
//
// -1 means unlimited on these settings
// just like their counterpart functions
// on torrent_handle

76
include/libtorrent/session.hpp
View File

@ -113,12 +113,28 @@ namespace libtorrent
#define TORRENT_LOGPATH_ARG_DEFAULT
#endif
// The session holds all state that spans multiple torrents. Among other things it runs the network
// loop and manages all torrents.
// Once it's created, the session 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.
class TORRENT_EXPORT session: public boost::noncopyable
{
public:
// 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
// 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
// the parameters, see ``listen_on()`` function.
//
// The flags paramater can be used to start default features (upnp & nat-pmp) and default plugins
// (ut_metadata, ut_pex and smart_ban). The default is to start those things. If you do not want
// them to start, pass 0 as the flags parameter.
//
// The ``alert_mask`` is the same mask that you would send to `set_alert_mask()`_.
session(fingerprint const& print = fingerprint("LT"
, LIBTORRENT_VERSION_MAJOR, LIBTORRENT_VERSION_MINOR, 0, 0)
, int flags = start_default_features | add_default_plugins
@ -132,9 +148,7 @@ namespace libtorrent
#endif
start(flags);
}
session(
fingerprint const& print
session(fingerprint const& print
, std::pair<int, int> listen_port_range
, char const* listen_interface = "0.0.0.0"
, int flags = start_default_features | add_default_plugins
@ -151,6 +165,11 @@ namespace libtorrent
start(flags);
}
// The destructor of session 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 session
// returns. So, it's advised that any kind of interface (such as windows) are closed before
// destructing the session object. Because it can take a few second for it to finish. The
// timeout can be set with ``set_settings()``.
~session();
enum save_state_flags_t
@ -172,6 +191,17 @@ namespace libtorrent
save_tracker_proxy = save_proxy
#endif
};
// loads and saves all session settings, including dht_settings, encryption settings and proxy
// 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()`_.
//
// 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
// torrents). see save_state_flags_t
void save_state(entry& e, boost::uint32_t flags = 0xffffffff) const;
void load_state(lazy_entry const& e);
@ -190,6 +220,25 @@ namespace libtorrent
// returns an invalid handle in case the torrent doesn't exist
torrent_handle find_torrent(sha1_hash const& info_hash) const;
// 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
// waiting for the torrent to add. Notification of the torrent being added is sent
// as add_torrent_alert_.
//
// 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
// 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
// torrent.
//
// all torrent_handles must be destructed before the session is destructed!
#ifndef BOOST_NO_EXCEPTIONS
torrent_handle add_torrent(add_torrent_params const& params);
@ -235,8 +284,29 @@ namespace libtorrent
#endif
#endif
// In case you want to destruct the session asynchrounously, you can request a session
// destruction proxy. If you don't do this, the destructor of the session object will
// block while the trackers are contacted. If you keep one ``session_proxy`` to the
// session when destructing it, the destructor will not block, but start to close down
// the session, the destructor of the proxy will then synchronize the threads. So, the
// destruction of the session is performed from the ``session`` destructor call until the
// ``session_proxy`` destructor call. The ``session_proxy`` does not have any operations
// on it (since the session is being closed down, no operations are allowed on it). The
// only valid operation is calling the destructor::
//
// class session_proxy
// {
// public:
// session_proxy();
// ~session_proxy()
// };
session_proxy abort() { return session_proxy(m_impl); }
// Pausing the session 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 session pause state is separate from
// the torrent pause state. A torrent is inactive if it is paused or if the session is
// paused.
void pause();
void resume();
bool is_paused() const;