premiere
/
premiere-libtorrent
2
2
Fork 1
Code Issues Pull Requests Releases Wiki Activity

a bunch of documentation fixes

This commit is contained in:
Arvid Norberg 2013-11-29 05:29:39 +00:00
parent 4152e06011
commit cd5af8897a
24 changed files with 297 additions and 151 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
docs/gen_reference_doc.py
View File

@ -305,13 +305,12 @@ def parse_class(lno, lines, filename):
print 'WARNING: member function "%s" is not documented: \x1b[34m%s:%d\x1b[0m' \
% (name + '::' + first_item(current_fun['names']), filename, lno)
funs.append(current_fun)
context = ''
blanks = 0
context = ''
blanks = 0
continue
if looks_like_variable(l):
if not is_visible(context):
context = ''
continue
n = l.split(' ')[-1].split(':')[0].split(';')[0]
if context == '' and blanks == 0 and len(fields):
@ -327,14 +326,17 @@ def parse_class(lno, lines, filename):
continue
if l.startswith('enum '):
enum, lno = parse_enum(lno - 1, lines, filename)
if enum != None and is_visible(context):
enum['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)
enums.append(enum)
context = ''
if not is_visible(context):
consume_block(lno - 1, lines)
else:
enum, lno = parse_enum(lno - 1, lines, filename)
if enum != None:
enum['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)
enums.append(enum)
context = ''
continue
context = ''
@ -441,6 +443,13 @@ def consume_comment(lno, lines):
return lno
def trim_define(l):
return l.replace('#ifndef', '').replace('#ifdef', '') \
.replace('#if', '').replace('defined', '') \
.replace('TORRENT_USE_IPV6', '').replace('TORRENT_NO_DEPRECATE', '') \
.replace('||', '').replace('&&', '').replace('(', '').replace(')','') \
.replace('!', '').replace('\\', '').strip()
def consume_ifdef(lno, lines, warn_on_ifdefs = False):
l = lines[lno].strip()
lno += 1
@ -451,17 +460,24 @@ def consume_ifdef(lno, lines, warn_on_ifdefs = False):
if verbose: print 'prep %s' % l
if warn_on_ifdefs and ('TORRENT_DEBUG' in l or 'TORRENT_DISABLE_FULL_STATS' in l):
print '\x1b[31mWARNING: possible ABI breakage in public struct!\x1b[34m %s:%d\x1b[0m' % \
(filename, lno)
while l.endswith('\\'):
lno += 1
l += lines[lno].strip()
if verbose: print 'prep %s' % lines[lno].trim()
define = trim_define(l)
print '\x1b[31mWARNING: possible ABI breakage in public struct! "%s" \x1b[34m %s:%d\x1b[0m' % \
(define, filename, lno)
# we've already warned once, no need to do it twice
warn_on_ifdefs = False
if warn_on_ifdefs and '#if' in l:
define = l.replace('#ifndef', '').replace('#ifdef', '') \
.replace('#if', '').replace('defined', '') \
.replace('TORRENT_USE_IPV6', '').replace('TORRENT_NO_DEPRECATE', '') \
.replace('||', '').replace('&&', '').replace('(', '').replace(')','') \
.replace('!', '').strip()
while l.endswith('\\'):
lno += 1
l += lines[lno].strip()
if verbose: print 'prep %s' % lines[lno].trim()
define = trim_define(l)
if define != '':
print '\x1b[31msensitive define in public struct: "%s"\x1b[34m %s:%d\x1b[0m' % (define, filename, lno)
print '\x1b[33msensitive define in public struct: "%s"\x1b[34m %s:%d\x1b[0m' % (define, filename, lno)
if l == '#ifndef TORRENT_NO_DEPRECATE' or \
l == '#ifdef TORRENT_DEBUG' or \
@ -543,6 +559,9 @@ for filename in files:
if verbose: print 'xx %s' % l
continue
if 'TORRENT_DEPRECATED' in l:
if ('class ' in l or 'struct ' in l) and not ';' in l:
lno = consume_block(lno - 1, lines)
context = ''
blanks += 1
if verbose: print 'xx %s' % l
continue
@ -573,8 +592,8 @@ for filename in files:
print 'WARNING: function "%s" is not documented: \x1b[34m%s:%d\x1b[0m' \
% (first_item(current_fun['names']), filename, lno)
functions.append(current_fun)
context = ''
blanks = 0
context = ''
continue
if ('class ' in l or 'struct ' in l) and not ';' in l:
@ -584,13 +603,16 @@ for filename in files:
continue
if l.startswith('enum '):
current_enum, lno = parse_enum(lno - 1, lines, filename)
if current_enum != None and is_visible(context):
current_enum['desc'] = context
if context == '':
print 'WARNING: enum "%s" is not documented: \x1b[34m%s:%d\x1b[0m' \
% (current_enum['name'], filename, lno)
enums.append(current_enum)
if not is_visible(context):
consume_block(lno - 1, lines)
else:
current_enum, lno = parse_enum(lno - 1, lines, filename)
if current_enum != None and is_visible(context):
current_enum['desc'] = context
if context == '':
print 'WARNING: enum "%s" is not documented: \x1b[34m%s:%d\x1b[0m' \
% (current_enum['name'], filename, lno)
enums.append(current_enum)
context = ''
blanks += 1
continue

3
include/libtorrent/add_torrent_params.hpp
View File

@ -318,6 +318,9 @@ namespace libtorrent
// flags controlling aspects of this torrent and how it's added. See flags_t for details.
boost::uint64_t flags;
// set this to the info hash of the torrent to add in case the info-hash
// is the only known property of the torrent. i.e. you don't have a
// .torrent file nor a magnet link.
sha1_hash info_hash;
// ``max_uploads``, ``max_connections``, ``upload_limit``, ``download_limit`` correspond

1
include/libtorrent/error_code.hpp
View File

@ -544,6 +544,7 @@ namespace libtorrent
#endif // BOOST_VERSION < 103600
#endif // BOOST_VERSION < 103500
// internal
inline boost::system::error_category const& generic_category()
{ return get_posix_category(); }

10
include/libtorrent/extensions.hpp
View File

@ -82,7 +82,7 @@ POSSIBILITY OF SUCH DAMAGE.
// ================
//
// The plugin interface consists of three base classes that the plugin may
// implement. These are called ``plugin``, ``torrent_plugin`` and ``peer_plugin``.
// implement. These are called plugin, torrent_plugin and peer_plugin.
// They are found in the ``<libtorrent/extensions.hpp>`` header.
//
// These plugins are instantiated for each session, torrent and possibly each peer,
@ -248,7 +248,7 @@ namespace libtorrent
// function).
//
// If you need an extension to the peer connection (which most plugins do) you
// are supposed to return an instance of your ``peer_plugin`` class. Which in
// are supposed to return an instance of your peer_plugin class. Which in
// turn will have its hook functions called on event specific to that peer.
//
// The ``peer_connection`` will be valid as long as the ``shared_ptr`` is being
@ -315,6 +315,12 @@ namespace libtorrent
int /*src*/, int /*flags*/) {}
};
// peer plugins are associated with a specific peer. A peer could be
// both a regular bittorrent peer (``bt_peer_connection``) or one of the
// web seed connections (``web_peer_connection`` or ``http_seed_connection``).
// In order to only attach to certain peers, make your
// torrent_plugin::new_connection only return a plugin for certain peer
// connection types
struct TORRENT_EXPORT peer_plugin
{
// hidden

4
include/libtorrent/extensions/lt_trackers.hpp
View File

@ -48,6 +48,10 @@ namespace libtorrent
{
struct torrent_plugin;
class torrent;
// constructor function for the trackers exchange extension. This can
// either be passed in the add_torrent_params::extensions field, or
// via torrent_handle::add_extension().
boost::shared_ptr<torrent_plugin> TORRENT_EXPORT create_lt_trackers_plugin(torrent*, void*);
}

12
include/libtorrent/extensions/metadata_transfer.hpp
View File

@ -48,7 +48,17 @@ namespace libtorrent
{
struct torrent_plugin;
class torrent;
TORRENT_EXPORT boost::shared_ptr<torrent_plugin> create_metadata_plugin(torrent*, void*);
#ifndef TORRENT_NO_DEPRECATE
// constructor function for the metadata transfer extension. This
// extension has been superceded by the ut_metadata extension and
// is deprecated. It can be either be passed in the
// add_torrent_params::extensions field, or
// via torrent_handle::add_extension().
TORRENT_DEPRECATED_PREFIX
TORRENT_EXPORT boost::shared_ptr<torrent_plugin>
create_metadata_plugin(torrent*, void*) TORRENT_DEPRECATED;
#endif
}
#endif // TORRENT_METADATA_TRANSFER_HPP_INCLUDED

7
include/libtorrent/extensions/smart_ban.hpp
View File

@ -48,6 +48,13 @@ namespace libtorrent
{
struct torrent_plugin;
class torrent;
// constructor function for the smart ban extension. The extension keeps
// track of the data peers have sent us for failing pieces and once the
// piece completes and passes the hash check bans the peers that turned
// out to have sent corrupt data.
// This function can either be passed in the add_torrent_params::extensions
// field, or via torrent_handle::add_extension().
TORRENT_EXPORT boost::shared_ptr<torrent_plugin> create_smart_ban_plugin(torrent*, void*);
}

10
include/libtorrent/extensions/ut_metadata.hpp
View File

@ -48,6 +48,16 @@ namespace libtorrent
{
struct torrent_plugin;
class torrent;
// constructor function for the ut_metadata extension. The ut_metadata
// extension allows peers to request the .torrent file (or more
// specifically the 'info'-dictionary of the .torrent file) from each
// other. This is the main building block in making magnet links work.
// This extension is enabled by default unless explicitly disabled in
// the session constructor.
//
// This can either be passed in the add_torrent_params::extensions field, or
// via torrent_handle::add_extension().
TORRENT_EXPORT boost::shared_ptr<torrent_plugin> create_ut_metadata_plugin(torrent*, void*);
}

9
include/libtorrent/extensions/ut_pex.hpp
View File

@ -48,6 +48,15 @@ namespace libtorrent
{
struct torrent_plugin;
class torrent;
// constructor function for the ut_pex extension. The ut_pex
// extension allows peers to gossip about their connections, allowing
// the swarm stay well connected and peers aware of more peers in the
// swarm. This extension is enabled by default unless explicitly disabled in
// the session constructor.
//
// This can either be passed in the add_torrent_params::extensions field, or
// via torrent_handle::add_extension().
TORRENT_EXPORT boost::shared_ptr<torrent_plugin> create_ut_pex_plugin(torrent*, void*);
}

1
include/libtorrent/file_storage.hpp
View File

@ -161,6 +161,7 @@ namespace libtorrent
name_is_owned = (1<<12)-1,
not_a_symlink = (1<<15)-1
};
// the offset of this file inside the torrent
boost::uint64_t offset:48;

17
include/libtorrent/ip_filter.hpp
View File

@ -269,8 +269,11 @@ namespace detail
// A default constructed ip_filter does not filter any address.
struct TORRENT_EXPORT ip_filter
{
// the flags defined for an IP range
enum access_flags
{
// indicates that IPs in this range should not be connected
// to nor accepted as incoming connections
blocked = 1
};
@ -321,16 +324,30 @@ private:
#endif
};
// the port filter maps non-overlapping port ranges to flags. This
// is primarily used to indicate whether a range of ports should
// be connected to or not. The default is to have the full port
// range (0-65535) set to flag 0.
class TORRENT_EXPORT port_filter
{
public:
// the defined flags for a port range
enum access_flags
{
// this flag indicates that destination ports in the
// range should not be connected to
blocked = 1
};
// set the flags for the specified port range (``first``, ``last``) to
// ``flags`` overwriting any existing rule for those ports. The range
// is inclusive, i.e. the port ``last`` also has the flag set on it.
void add_rule(boost::uint16_t first, boost::uint16_t last, int flags);
// test the specified port (``port``) for whether it is blocked
// or not. The returned value is the flags set for this port.
// see acces_flags.
int access(boost::uint16_t port) const;
private:

84
include/libtorrent/peer_info.hpp
View File

@ -42,6 +42,8 @@ POSSIBILITY OF SUCH DAMAGE.
namespace libtorrent
{
// holds information and statistics about one peer
// that libtorrent is connected to
struct TORRENT_EXPORT peer_info
{
enum peer_flags_t
@ -59,76 +61,85 @@ namespace libtorrent
remote_choked = 0x8,
// means that this peer supports the
// `extension protocol`__.
// `extension protocol`__.
//
// __ extension_protocol.html
supports_extensions = 0x10,
// The connection was initiated by us, the peer has a
// The connection was initiated by us, the peer has a
// listen port open, and that port is the same as in the
// address of this peer. If this flag is not set, this
// address of this peer. If this flag is not set, this
// peer connection was opened by this peer connecting to
// us.
// us.
local_connection = 0x20,
// The connection is opened, and waiting for the
// handshake. Until the handshake is done, the peer
// cannot be identified.
// The connection is opened, and waiting for the
// handshake. Until the handshake is done, the peer
// cannot be identified.
handshake = 0x40,
// The connection is in a half-open state (i.e. it is
// being connected).
// The connection is in a half-open state (i.e. it is
// being connected).
connecting = 0x80,
// The connection is currently queued for a connection
// attempt. This may happen if there is a limit set on
// the number of half-open TCP connections.
// The connection is currently queued for a connection
// attempt. This may happen if there is a limit set on
// the number of half-open TCP connections.
queued = 0x100,
// The peer has participated in a piece that failed the
// The peer has participated in a piece that failed the
// hash check, and is now "on parole", which means we're
// only requesting whole pieces from this peer until
// it either fails that piece or proves that it doesn't
// send bad data.
// only requesting whole pieces from this peer until
// it either fails that piece or proves that it doesn't
// send bad data.
on_parole = 0x200,
// This peer is a seed (it has all the pieces).
// This peer is a seed (it has all the pieces).
seed = 0x400,
// This peer is subject to an optimistic unchoke. It has
// been unchoked for a while to see if it might unchoke
// us in return an earn an upload/unchoke slot. If it
// been unchoked for a while to see if it might unchoke
// us in return an earn an upload/unchoke slot. If it
// doesn't within some period of time, it will be choked
// and another peer will be optimistically unchoked.
// and another peer will be optimistically unchoked.
optimistic_unchoke = 0x800,
// This peer has recently failed to send a block within
// the request timeout from when the request was sent.
// This peer has recently failed to send a block within
// the request timeout from when the request was sent.
// We're currently picking one block at a time from this
// peer.
// peer.
snubbed = 0x1000,
// This peer has either explicitly (with an extension)
// or implicitly (by becoming a seed) told us that it
// will not downloading anything more, regardless of
// which pieces we have.
// This peer has either explicitly (with an extension)
// or implicitly (by becoming a seed) told us that it
// will not downloading anything more, regardless of
// which pieces we have.
upload_only = 0x2000,
// This means the last time this peer picket a piece,
// it could not pick as many as it wanted because there
// were not enough free ones. i.e. all pieces this peer
// has were already requested from other peers.
// This means the last time this peer picket a piece,
// it could not pick as many as it wanted because there
// were not enough free ones. i.e. all pieces this peer
// has were already requested from other peers.
endgame_mode = 0x4000,
// This flag is set if the peer was in holepunch mode
// when the connection succeeded. This typically only
// happens if both peers are behind a NAT and the peers
// connect via the NAT holepunch mechanism.
// This flag is set if the peer was in holepunch mode
// when the connection succeeded. This typically only
// happens if both peers are behind a NAT and the peers
// connect via the NAT holepunch mechanism.
holepunched = 0x8000,
// indicates that this socket is runnin on top of the
// I2P transport.
i2p_socket = 0x10000,
// indicates that this socket is a uTP socket
utp_socket = 0x20000,
// this connection is obfuscated with RC4
rc4_encrypted = 0x100000,
// the handshake of this connection was obfuscated
// with a diffie-hellman exchange
plaintext_encrypted = 0x200000
};
@ -136,6 +147,9 @@ namespace libtorrent
// any combination of the peer_flags_t enum.
unsigned int flags;
// the flags indicating which sources a peer can
// have come from. A peer may have been seen from
// multiple sources
enum peer_source_flags
{
// The peer was received from the tracker.

3
include/libtorrent/peer_request.hpp
View File

@ -35,6 +35,9 @@ POSSIBILITY OF SUCH DAMAGE.
namespace libtorrent
{
// represents a byte range within a piece. Internally this is
// is used for incoming piece requests.
struct TORRENT_EXPORT peer_request
{
// the index of the piece in which the range starts.

16
include/libtorrent/ptime.hpp
View File

@ -57,7 +57,9 @@ namespace libtorrent
// libtorrent time_duration type
struct TORRENT_EXPORT time_duration
{
// hidden
time_duration() {}
time_duration operator/(int rhs) const { return time_duration(diff / rhs); }
explicit time_duration(boost::int64_t d) : diff(d) {}
time_duration& operator-=(time_duration const& c) { diff -= c.diff; return *this; }
@ -73,8 +75,10 @@ namespace libtorrent
// This type represents a point in time.
struct TORRENT_EXPORT ptime
{
// hidden
ptime() {}
explicit ptime(boost::uint64_t t): time(t) {}
ptime& operator+=(time_duration rhs) { time += rhs.diff; return *this; }
ptime& operator-=(time_duration rhs) { time -= rhs.diff; return *this; }
@ -87,40 +91,28 @@ namespace libtorrent
// hidden
inline bool operator>(ptime lhs, ptime rhs)
{ return lhs.time > rhs.time; }
// hidden
inline bool operator>=(ptime lhs, ptime rhs)
{ return lhs.time >= rhs.time; }
// hidden
inline bool operator<=(ptime lhs, ptime rhs)
{ return lhs.time <= rhs.time; }
// hidden
inline bool operator<(ptime lhs, ptime rhs)
{ return lhs.time < rhs.time; }
// hidden
inline bool operator!=(ptime lhs, ptime rhs)
{ return lhs.time != rhs.time;}
// hidden
inline bool operator==(ptime lhs, ptime rhs)
{ return lhs.time == rhs.time;}
// hidden
inline bool operator==(time_duration lhs, time_duration rhs)
{ return lhs.diff == rhs.diff; }
// hidden
inline bool operator<(time_duration lhs, time_duration rhs)
{ return lhs.diff < rhs.diff; }
// hidden
inline bool operator<=(time_duration lhs, time_duration rhs)
{ return lhs.diff <= rhs.diff; }
// hidden
inline bool operator>(time_duration lhs, time_duration rhs)
{ return lhs.diff > rhs.diff; }
// hidden
inline bool operator>=(time_duration lhs, time_duration rhs)
{ return lhs.diff >= rhs.diff; }
// hidden
inline time_duration operator*(time_duration lhs, int rhs)
{ return time_duration(boost::int64_t(lhs.diff * rhs)); }
// hidden
inline time_duration operator*(int lhs, time_duration rhs)
{ return time_duration(boost::int64_t(lhs * rhs.diff)); }

5
include/libtorrent/session.hpp
View File

@ -261,6 +261,7 @@ namespace libtorrent
// is on by default. See add_torrent_params_.
void post_torrent_updates();
// internal
io_service& get_io_service();
// ``find_torrent()`` looks for a torrent with the given info-hash. In case there
@ -523,17 +524,17 @@ namespace libtorrent
void load_asnum_db(char const* file);
void load_country_db(char const* file);
int as_for_ip(address const& addr);
#ifndef TORRENT_NO_DEPRECATE
#if TORRENT_USE_WSTRING
// all wstring APIs are deprecated since 0.16.11
// instead, use the wchar -> utf8 conversion functions
// and pass in utf8 strings
#ifndef TORRENT_NO_DEPRECATE
TORRENT_DEPRECATED_PREFIX
void load_country_db(wchar_t const* file) TORRENT_DEPRECATED;
TORRENT_DEPRECATED_PREFIX
void load_asnum_db(wchar_t const* file) TORRENT_DEPRECATED;
#endif // TORRENT_NO_DEPRECATE
#endif // TORRENT_USE_WSTRING
#endif // TORRENT_NO_DEPRECATE
#endif // TORRENT_DISABLE_GEO_IP
#ifndef TORRENT_NO_DEPRECATE

43
include/libtorrent/session_status.hpp
View File

@ -40,18 +40,43 @@ POSSIBILITY OF SUCH DAMAGE.
namespace libtorrent
{
struct dht_lookup
// holds statistics about a current dht_lookup operation.
// a DHT lookup is the travesal of nodes, looking up a
// set of target nodes in the DHT for retrieving and possibly
// storing information in the DHT
struct TORRENT_EXPORT dht_lookup
{
// string literal indicating which kind of lookup this is
char const* type;
// the number of outstanding request to individual nodes
// this lookup has right now
int outstanding_requests;
// the total number of requests that have timed out so far
// for this lookup
int timeouts;
// the total number of responses we have received for this
// lookup so far for this lookup
int responses;
// the branch factor for this lookup. This is the number of
// nodes we keep outstanding requests to in parallel by default.
// when nodes time out we may increase this.
int branch_factor;
// the number of nodes left that could be queries for this
// lookup. Many of these are likely to be part of the trail
// while performing the lookup and would never end up actually
// being queried.
int nodes_left;
// the number of seconds ago the
// last message was sent that's still
// outstanding
int last_sent;
// the number of outstanding requests
// that have exceeded the short timeout
// and are considered timed out in the
@ -60,24 +85,31 @@ namespace libtorrent
int first_timeout;
};
struct dht_routing_bucket
// holds dht routing table stats
struct TORRENT_EXPORT dht_routing_bucket
{
// the total number of nodes and replacement nodes
// in the routing table
int num_nodes;
int num_replacements;
// number of seconds since last activity
int last_active;
};
struct utp_status
// holds counters and gauges for the uTP sockets
struct TORRENT_EXPORT utp_status
{
// gauges
// gauges. These are snapshots of the number of
// uTP sockets in each respective state
int num_idle;
int num_syn_sent;
int num_connected;
int num_fin_sent;
int num_close_wait;
// counters
// counters. These are monotonically increasing
// and cumulative counters for their respective event.
boost::uint64_t packet_loss;
boost::uint64_t timeout;
boost::uint64_t packets_in;
@ -92,6 +124,7 @@ namespace libtorrent
boost::uint64_t redundant_pkts_in;
};
// contains session wide state and counters
struct TORRENT_EXPORT session_status
{
// false as long as no incoming connections have been

9
include/libtorrent/settings.hpp
View File

@ -41,9 +41,12 @@ namespace libtorrent
struct lazy_entry;
class entry;
enum { std_string, character, integer
, floating_point, boolean, size_integer
, time_integer };
// internal
enum struct_field_type_t
{
std_string, character, integer, floating_point,
boolean, size_integer, time_integer
};
// this is used to map struct entries
// to names in a bencoded dictionary to

5
include/libtorrent/sha1_hash.hpp
View File

@ -69,7 +69,7 @@ namespace libtorrent
enum { number_size = 20 };
public:
// the number of bytes of the number
enum { size = number_size };
static const int size = number_size;
// constructs an all-sero sha1-hash
sha1_hash() { clear(); }
@ -258,9 +258,10 @@ namespace libtorrent
typedef const unsigned char* const_iterator;
typedef unsigned char* iterator;
// start and end iterators for the hash. The value type
// of these iterators is ``unsigned char``.
const_iterator begin() const { return m_number; }
const_iterator end() const { return m_number+number_size; }
iterator begin() { return m_number; }
iterator end() { return m_number+number_size; }

17
include/libtorrent/storage.hpp
View File

@ -152,15 +152,7 @@ namespace libtorrent
, std::vector<std::pair<size_type, std::time_t> > const& sizes
, bool compact_mode
, std::string* error = 0);
/*
struct TORRENT_EXTRA_EXPORT file_allocation_failed: std::exception
{
file_allocation_failed(const char* error_msg): m_msg(error_msg) {}
virtual const char* what() const throw() { return m_msg.c_str(); }
virtual ~file_allocation_failed() throw() {}
std::string m_msg;
};
*/
struct TORRENT_EXTRA_EXPORT partial_hash
{
partial_hash(): offset(0) {}
@ -190,13 +182,14 @@ namespace libtorrent
// compact allocation mode it won't).
//
// libtorrent comes with two built-in storage implementations; ``default_storage``
// and ``disabled_storage``. Their constructor functions are called ``default_storage_constructor``
// and ``disabled_storage``. Their constructor functions are called default_storage_constructor()
// and ``disabled_storage_constructor`` respectively. The disabled storage does
// just what it sounds like. It throws away data that's written, and it
// reads garbage. It's useful mostly for benchmarking and profiling purpose.
//
struct TORRENT_EXPORT storage_interface
{
// hidden
storage_interface(): m_disk_pool(0), m_settings(0) {}
// This function is called when the storage is to be initialized. The default storage
@ -247,6 +240,8 @@ namespace libtorrent
// negative return value indicates an error
virtual int write(const char* buf, int slot, int offset, int size) = 0;
// returns the offset on the physical storage medium for the
// byte at offset ``offset`` in slot ``slot``.
virtual size_type physical_offset(int slot, int offset) = 0;
// This function is optional. It is supposed to return the first piece, starting at
@ -395,6 +390,8 @@ namespace libtorrent
public:
default_storage(file_storage const& fs, file_storage const* mapped, std::string const& path
, file_pool& fp, std::vector<boost::uint8_t> const& file_prio);
// hidden
~default_storage();
#ifndef TORRENT_NO_DEPRECATE

5
include/libtorrent/storage_defs.hpp
View File

@ -65,10 +65,15 @@ namespace libtorrent
typedef boost::function<storage_interface*(file_storage const&, file_storage const*
, std::string const&, file_pool&, std::vector<boost::uint8_t> const&)> storage_constructor_type;
// the constructor function for the regular file storage. This is the
// default value for add_torrent_params::storage.
TORRENT_EXPORT storage_interface* default_storage_constructor(
file_storage const&, file_storage const* mapped, std::string const&, file_pool&
, std::vector<boost::uint8_t> const&);
// the constructor function for the disabled storage. This can be used for
// testing and benchmarking. It will throw away any data written to
// it and return garbage for anything read from it.
TORRENT_EXPORT storage_interface* disabled_storage_constructor(
file_storage const&, file_storage const* mapped, std::string const&, file_pool&
, std::vector<boost::uint8_t> const&);

90
include/libtorrent/torrent_handle.hpp
View File

@ -421,6 +421,11 @@ namespace libtorrent
void remove_http_seed(std::string const& url) const;
std::set<std::string> http_seeds() const;
// add the specified extension to this torrent. The ``ext`` argument is
// a function that will be called from within libtorrent's context
// passing in the internal torrent object and the specified userdata
// pointer. The function is expected to return a shared pointer to
// a torrent_plugin instance.
void add_extension(boost::function<boost::shared_ptr<torrent_plugin>(torrent*, void*)> const& ext
, void* userdata = 0);
@ -499,18 +504,24 @@ namespace libtorrent
// to peers again, as normal.
void force_recheck() const;
enum save_resume_flags_t { flush_disk_cache = 1, save_info_dict = 2 };
// flags used in the save_resume_data call to control additional
// actions or fields to save.
enum save_resume_flags_t
{
// the disk cache will be flushed before creating the resume data. This avoids a problem with
// file timestamps in the resume data in case the cache hasn't been flushed yet.
flush_disk_cache = 1,
// the resume data will contain the metadata
// from the torrent file as well. This is default for any torrent that's added without a torrent
// file (such as a magnet link or a URL).
save_info_dict = 2
};
// ``save_resume_data()`` generates fast-resume data and returns it as an entry. This entry
// is suitable for being bencoded. For more information about how fast-resume works, see fast-resume_.
//
// The ``flags`` argument is a bitmask of flags ORed together. If the flag ``torrent_handle::flush_cache``
// is set, the disk cache will be flushed before creating the resume data. This avoids a problem with
// file timestamps in the resume data in case the cache hasn't been flushed yet.
//
// If the flag ``torrent_handle::save_info_dict`` is set, the resume data will contain the metadata
// from the torrent file as well. This is default for any torrent that's added without a torrent
// file (such as a magnet link or a URL).
// The ``flags`` argument is a bitmask of flags ORed together. see save_resume_flags_t
//
// This operation is asynchronous, ``save_resume_data`` will return immediately. The resume data
// is delivered when it's done through an save_resume_data_alert.
@ -977,8 +988,8 @@ namespace libtorrent
// when either a file_renamed_alert or file_rename_failed_alert is posted.
void rename_file(int index, std::string const& new_name) const;
#if TORRENT_USE_WSTRING
#ifndef TORRENT_NO_DEPRECATE
#if TORRENT_USE_WSTRING
// all wstring APIs are deprecated since 0.16.11
// instead, use the wchar -> utf8 conversion functions
// and pass in utf8 strings
@ -986,8 +997,8 @@ namespace libtorrent
void move_storage(std::wstring const& save_path, int flags = 0) const TORRENT_DEPRECATED;
TORRENT_DEPRECATED_PREFIX
void rename_file(int index, std::wstring const& new_name) const TORRENT_DEPRECATED;
#endif // TORRENT_NO_DEPRECATE
#endif // TORRENT_USE_WSTRING
#endif // TORRENT_NO_DEPRECATE
// Enables or disabled super seeding/initial seeding for this torrent. The torrent
// needs to be a seed for this to take effect.
@ -1018,10 +1029,6 @@ namespace libtorrent
: m_torrent(t)
{}
#if defined TORRENT_DEBUG && !defined TORRENT_DISABLE_INVARIANT_CHECKS
void check_invariant() const;
#endif
boost::weak_ptr<torrent> m_torrent;
};
@ -1043,64 +1050,69 @@ namespace libtorrent
enum state_t
{
// The torrent is in the queue for being checked. But there
// currently is another torrent that are being checked.
// This torrent will wait for its turn.
// currently is another torrent that are being checked.
// This torrent will wait for its turn.
queued_for_checking,
// The torrent has not started its download yet, and is
// currently checking existing files.
// currently checking existing files.
checking_files,
// The torrent is trying to download metadata from peers.
// The torrent is trying to download metadata from peers.
// This assumes the metadata_transfer extension is in use.
downloading_metadata,
// The torrent is being downloaded. This is the state
// The torrent is being downloaded. This is the state
// most torrents will be in most of the time. The progress
// meter will tell how much of the files that has been
// downloaded.
// meter will tell how much of the files that has been
// downloaded.
downloading,
// In this state the torrent has finished downloading but
// In this state the torrent has finished downloading but
// still doesn't have the entire torrent. i.e. some pieces
// are filtered and won't get downloaded.
// are filtered and won't get downloaded.
finished,
// In this state the torrent has finished downloading and
// is a pure seeder.
// is a pure seeder.
seeding,
// If the torrent was started in full allocation mode, this
// indicates that the (disk) storage for the torrent is
// allocated.
// indicates that the (disk) storage for the torrent is
// allocated.
allocating,
// The torrent is currently checking the fastresume data and
// comparing it to the files on disk. This is typically
// completed in a fraction of a second, but if you add a
// large number of torrents at once, they will queue up.
// 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.
checking_resume_data
};
// may be set to an error message describing why the torrent was paused, in
// case it was paused by an error. If the torrent is not paused or if it's paused but
// not because of an error, this string is empty.
// may be set to an error message describing why the torrent
// was paused, in case it was paused by an error. If the torrent
// is not paused or if it's paused but not because of an error,
// this string is empty.
std::string error;
// the path to the directory where this torrent's files are stored.
// It's typically the path as was given to async_add_torrent() or add_torrent() when this torrent
// was started. This field is only included if the torrent status is queried with
// It's typically the path as was given to async_add_torrent() or
// add_torrent() when this torrent was started. This field is only
// included if the torrent status is queried with
// ``torrent_handle::query_save_path``.
std::string save_path;
// the name of the torrent. Typically this is derived from the .torrent file.
// In case the torrent was started without metadata, and hasn't completely received it yet,
// it returns the name given to it when added to the session. See ``session::add_torrent``.
// This field is only included if the torrent status is queried with ``torrent_handle::query_name``.
// the name of the torrent. Typically this is derived from the
// .torrent file. In case the torrent was started without metadata,
// and hasn't completely received it yet, it returns the name given
// to it when added to the session. See ``session::add_torrent``.
// This field is only included if the torrent status is queried
// with ``torrent_handle::query_name``.
std::string name;
// set to point to the ``torrent_info`` object for this torrent. It's
// only included if the torrent status is queried with ``torrent_handle::query_torrent_file``.
// only included if the torrent status is queried with
// ``torrent_handle::query_torrent_file``.
boost::intrusive_ptr<const torrent_info> torrent_file;
// the time until the torrent will announce itself to the tracker.

12
include/libtorrent/torrent_info.hpp
View File

@ -331,30 +331,30 @@ namespace libtorrent
torrent_info(lazy_entry const& torrent_file, int flags = 0);
torrent_info(char const* buffer, int size, int flags = 0);
torrent_info(std::string const& filename, int flags = 0);
#ifndef TORRENT_NO_DEPRECATE
#if TORRENT_USE_WSTRING
// all wstring APIs are deprecated since 0.16.11
// instead, use the wchar -> utf8 conversion functions
// and pass in utf8 strings
#ifndef TORRENT_NO_DEPRECATE
TORRENT_DEPRECATED_PREFIX
torrent_info(std::wstring const& filename, int flags = 0) TORRENT_DEPRECATED;
#endif // TORRENT_NO_DEPRECATE
#endif // TORRENT_USE_WSTRING
#endif // TORRENT_NO_DEPRECATE
#endif
torrent_info(torrent_info const& t, int flags = 0);
torrent_info(sha1_hash const& info_hash, int flags = 0);
torrent_info(lazy_entry const& torrent_file, error_code& ec, int flags = 0);
torrent_info(char const* buffer, int size, error_code& ec, int flags = 0);
torrent_info(std::string const& filename, error_code& ec, int flags = 0);
#ifndef TORRENT_NO_DEPRECATE
#if TORRENT_USE_WSTRING
// all wstring APIs are deprecated since 0.16.11
// instead, use the wchar -> utf8 conversion functions
// and pass in utf8 strings
#ifndef TORRENT_NO_DEPRECATE
TORRENT_DEPRECATED_PREFIX
torrent_info(std::wstring const& filename, error_code& ec, int flags = 0) TORRENT_DEPRECATED;
#endif // TORRENT_NO_DEPRECATE
#endif // TORRENT_USE_WSTRING
#endif // TORRENT_NO_DEPRECATE
// frees all storage associated with this torrent_info object
~torrent_info();
@ -392,15 +392,15 @@ namespace libtorrent
copy_on_write();
m_files.rename_file(index, new_filename);
}
#ifndef TORRENT_NO_DEPRECATE
#if TORRENT_USE_WSTRING
// all wstring APIs are deprecated since 0.16.11
// instead, use the wchar -> utf8 conversion functions
// and pass in utf8 strings
#ifndef TORRENT_NO_DEPRECATE
TORRENT_DEPRECATED_PREFIX
void rename_file(int index, std::wstring const& new_filename) TORRENT_DEPRECATED;
#endif // TORRENT_NO_DEPRECATE
#endif // TORRENT_USE_WSTRING
#endif // TORRENT_NO_DEPRECATE
// Remaps the file storage to a new file layout. This can be used to, for instance,
// download all data in a torrent to a single file, or to a number of fixed size

3
include/libtorrent/utp_stream.hpp
View File

@ -119,7 +119,8 @@ namespace libtorrent
*/
// internal: the different kinds of uTP packets
enum { ST_DATA = 0, ST_FIN, ST_STATE, ST_RESET, ST_SYN, NUM_TYPES };
enum utp_socket_state_t
{ ST_DATA, ST_FIN, ST_STATE, ST_RESET, ST_SYN, NUM_TYPES };
struct utp_header
{

6
src/torrent_handle.cpp
View File

@ -266,12 +266,6 @@ namespace libtorrent
}
#endif
#if defined TORRENT_DEBUG && !defined TORRENT_DISABLE_INVARIANT_CHECKS
void torrent_handle::check_invariant() const
{}
#endif
sha1_hash torrent_handle::info_hash() const
{
INVARIANT_CHECK;