move some documentation over to headers and make all links in reference documentation work
This commit is contained in:
Arvid Norberg
@@ -26,6 +26,26 @@ overviews = {}
|
||||
# maps names -> URL
|
||||
symbols = {}
|
||||
|
||||
# some pre-defined sections from the main manual
|
||||
|
||||
symbols = \
|
||||
{
|
||||
"queuing_": "manual.html#queuing",
|
||||
"fast-resume_": "manual.html#fast-resume",
|
||||
"storage-allocation_": "manual.html#storage-allocation",
|
||||
"alerts_": "manual.html#alerts",
|
||||
"upnp-and-nat-pmp_": "manual.html#upnp-and-nat-pmp",
|
||||
"http-seeding_": "manual.html#http-seeding",
|
||||
"metadata-from-peers_": "manual.html#metadata-from-peers",
|
||||
"magnet-links_": "manual.html#magnet-links",
|
||||
}
|
||||
|
||||
static_links = \
|
||||
{
|
||||
".. _`BEP 17`: http://bittorrent.org/beps/bep_0017.html",
|
||||
".. _`BEP 19`: http://bittorrent.org/beps/bep_0019.html"
|
||||
}
|
||||
|
||||
anon_index = 0
|
||||
|
||||
category_mapping = {
|
||||
@@ -638,12 +658,19 @@ def linkify_symbols(string):
|
||||
# preserve commas and dots at the end
|
||||
w = words[i].strip()
|
||||
trailing = ''
|
||||
if len(w) > 0 and (w[-1] == '.' or w[-1] == ','):
|
||||
if len(w) == 0: continue
|
||||
|
||||
if (w[-1] == '.' or w[-1] == ',' or (w[-1] == ')' and w[-2:-1] != '()')):
|
||||
trailing = w[-1]
|
||||
w = w[:-1]
|
||||
|
||||
|
||||
link_name = w;
|
||||
|
||||
if link_name[-1] == '_': link_name = link_name[:-1]
|
||||
|
||||
if w in symbols:
|
||||
words[i] = (leading_tabs * '\t') + print_link(w, symbols[w]) + trailing
|
||||
link_name = link_name.replace('-', ' ')
|
||||
words[i] = (leading_tabs * '\t') + print_link(link_name, symbols[w]) + trailing
|
||||
ret.append(' '.join(words))
|
||||
return '\n'.join(ret)
|
||||
|
||||
@@ -847,5 +874,8 @@ for cat in categories:
|
||||
|
||||
print >>out, dump_link_targets()
|
||||
|
||||
for i in static_links:
|
||||
print >>out, i
|
||||
|
||||
out.close()
|
||||
|
||||
|
||||
377
docs/manual.rst
377
docs/manual.rst
@@ -93,265 +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 customization
|
||||
=====================
|
||||
|
||||
You have some control over session configuration through the ``session_settings`` object. You
|
||||
create it and fill it with your settings and then use ``session::set_settings()``
|
||||
to apply them.
|
||||
|
||||
You have control over proxy and authorization settings and also the user-agent
|
||||
that will be sent to the tracker. The user-agent will also be used to identify the
|
||||
client with other peers.
|
||||
|
||||
session_settings
|
||||
----------------
|
||||
|
||||
::
|
||||
|
||||
struct session_settings
|
||||
{
|
||||
session_settings();
|
||||
int version;
|
||||
std::string user_agent;
|
||||
int tracker_completion_timeout;
|
||||
int tracker_receive_timeout;
|
||||
int stop_tracker_timeout;
|
||||
int tracker_maximum_response_length;
|
||||
|
||||
int piece_timeout;
|
||||
float request_queue_time;
|
||||
int max_allowed_in_request_queue;
|
||||
int max_out_request_queue;
|
||||
int whole_pieces_threshold;
|
||||
int peer_timeout;
|
||||
int urlseed_timeout;
|
||||
int urlseed_pipeline_size;
|
||||
int file_pool_size;
|
||||
bool allow_multiple_connections_per_ip;
|
||||
int max_failcount;
|
||||
int min_reconnect_time;
|
||||
int peer_connect_timeout;
|
||||
bool ignore_limits_on_local_network;
|
||||
int connection_speed;
|
||||
bool send_redundant_have;
|
||||
bool lazy_bitfields;
|
||||
int inactivity_timeout;
|
||||
int unchoke_interval;
|
||||
int optimistic_unchoke_interval;
|
||||
std::string announce_ip;
|
||||
int num_want;
|
||||
int initial_picker_threshold;
|
||||
int allowed_fast_set_size;
|
||||
|
||||
enum { no_piece_suggestions = 0, suggest_read_cache = 1 };
|
||||
int suggest_mode;
|
||||
int max_queued_disk_bytes;
|
||||
int handshake_timeout;
|
||||
bool use_dht_as_fallback;
|
||||
bool free_torrent_hashes;
|
||||
bool upnp_ignore_nonrouters;
|
||||
int send_buffer_watermark;
|
||||
int send_buffer_watermark_factor;
|
||||
|
||||
#ifndef TORRENT_NO_DEPRECATE
|
||||
bool auto_upload_slots;
|
||||
bool auto_upload_slots_rate_based;
|
||||
#endif
|
||||
|
||||
enum choking_algorithm_t
|
||||
{
|
||||
fixed_slots_choker,
|
||||
auto_expand_choker,
|
||||
rate_based_choker,
|
||||
bittyrant_choker
|
||||
};
|
||||
|
||||
int choking_algorithm;
|
||||
|
||||
enum seed_choking_algorithm_t
|
||||
{
|
||||
round_robin,
|
||||
fastest_upload,
|
||||
anti_leech
|
||||
};
|
||||
|
||||
int seed_choking_algorithm;
|
||||
|
||||
bool use_parole_mode;
|
||||
int cache_size;
|
||||
int cache_buffer_chunk_size;
|
||||
int cache_expiry;
|
||||
bool use_read_cache;
|
||||
bool explicit_read_cache;
|
||||
int explicit_cache_interval;
|
||||
|
||||
enum io_buffer_mode_t
|
||||
{
|
||||
enable_os_cache = 0,
|
||||
disable_os_cache_for_aligned_files = 1,
|
||||
disable_os_cache = 2
|
||||
};
|
||||
int disk_io_write_mode;
|
||||
int disk_io_read_mode;
|
||||
|
||||
std::pair<int, int> outgoing_ports;
|
||||
char peer_tos;
|
||||
|
||||
int active_downloads;
|
||||
int active_seeds;
|
||||
int active_dht_limit;
|
||||
int active_tracker_limit;
|
||||
int active_limit;
|
||||
bool auto_manage_prefer_seeds;
|
||||
bool dont_count_slow_torrents;
|
||||
int auto_manage_interval;
|
||||
float share_ratio_limit;
|
||||
float seed_time_ratio_limit;
|
||||
int seed_time_limit;
|
||||
int peer_turnover_interval;
|
||||
float peer_turnover;
|
||||
float peer_turnover_cutoff;
|
||||
bool close_redundant_connections;
|
||||
|
||||
int auto_scrape_interval;
|
||||
int auto_scrape_min_interval;
|
||||
|
||||
int max_peerlist_size;
|
||||
|
||||
int min_announce_interval;
|
||||
|
||||
bool prioritize_partial_pieces;
|
||||
int auto_manage_startup;
|
||||
|
||||
bool rate_limit_ip_overhead;
|
||||
|
||||
bool announce_to_all_trackers;
|
||||
bool announce_to_all_tiers;
|
||||
|
||||
bool prefer_udp_trackers;
|
||||
bool strict_super_seeding;
|
||||
|
||||
int seeding_piece_quota;
|
||||
|
||||
int max_sparse_regions;
|
||||
|
||||
bool lock_disk_cache;
|
||||
|
||||
int max_rejects;
|
||||
|
||||
int recv_socket_buffer_size;
|
||||
int send_socket_buffer_size;
|
||||
|
||||
bool optimize_hashing_for_speed;
|
||||
|
||||
int file_checks_delay_per_block;
|
||||
|
||||
enum disk_cache_algo_t
|
||||
{ lru, largest_contiguous, avoid_readback };
|
||||
|
||||
disk_cache_algo_t disk_cache_algorithm;
|
||||
|
||||
int read_cache_line_size;
|
||||
int write_cache_line_size;
|
||||
|
||||
int optimistic_disk_retry;
|
||||
bool disable_hash_checks;
|
||||
|
||||
int max_suggest_pieces;
|
||||
|
||||
bool drop_skipped_requests;
|
||||
|
||||
bool low_prio_disk;
|
||||
int local_service_announce_interval;
|
||||
int dht_announce_interval;
|
||||
|
||||
int udp_tracker_token_expiry;
|
||||
bool volatile_read_cache;
|
||||
bool guided_read_cache;
|
||||
bool default_cache_min_age;
|
||||
|
||||
int num_optimistic_unchoke_slots;
|
||||
bool no_atime_storage;
|
||||
int default_est_reciprocation_rate;
|
||||
int increase_est_reciprocation_rate;
|
||||
int decrease_est_reciprocation_rate;
|
||||
bool incoming_starts_queued_torrents;
|
||||
bool report_true_downloaded;
|
||||
bool strict_end_game_mode;
|
||||
|
||||
bool broadcast_lsd;
|
||||
|
||||
bool enable_outgoing_utp;
|
||||
bool enable_incoming_utp;
|
||||
bool enable_outgoing_tcp;
|
||||
bool enable_incoming_tcp;
|
||||
int max_pex_peers;
|
||||
bool ignore_resume_timestamps;
|
||||
bool no_recheck_incomplete_resume;
|
||||
bool anonymous_mode;
|
||||
bool force_proxy;
|
||||
int tick_interval;
|
||||
int share_mode_target;
|
||||
|
||||
int upload_rate_limit;
|
||||
int download_rate_limit;
|
||||
int local_upload_rate_limit;
|
||||
int local_download_rate_limit;
|
||||
int dht_upload_rate_limit;
|
||||
int unchoke_slots_limit;
|
||||
int half_open_limit;
|
||||
int connections_limit;
|
||||
|
||||
int utp_target_delay;
|
||||
int utp_gain_factor;
|
||||
int utp_min_timeout;
|
||||
int utp_syn_resends;
|
||||
int utp_num_resends;
|
||||
int utp_connect_timeout;
|
||||
bool utp_dynamic_sock_buf;
|
||||
int utp_loss_multiplier;
|
||||
|
||||
enum bandwidth_mixed_algo_t
|
||||
{
|
||||
prefer_tcp = 0,
|
||||
peer_proportional = 1
|
||||
|
||||
};
|
||||
int mixed_mode_algorithm;
|
||||
bool rate_limit_utp;
|
||||
|
||||
int listen_queue_size;
|
||||
|
||||
bool announce_double_nat;
|
||||
|
||||
int torrent_connect_boost;
|
||||
bool seeding_outgoing_connections;
|
||||
|
||||
bool no_connect_privileged_ports;
|
||||
int alert_queue_size;
|
||||
int max_metadata_size;
|
||||
bool smooth_connects;
|
||||
bool always_send_user_agent;
|
||||
bool apply_ip_filter_to_trackers;
|
||||
int read_job_every;
|
||||
bool use_disk_read_ahead;
|
||||
bool lock_files;
|
||||
|
||||
int ssl_listen;
|
||||
|
||||
int tracker_backoff;
|
||||
|
||||
bool ban_web_seeds;
|
||||
int max_http_recv_buffer_size;
|
||||
|
||||
bool support_share_mode;
|
||||
bool support_merkle_torrents;
|
||||
bool report_redundant_bytes;
|
||||
std::string handshake_client_version;
|
||||
bool use_disk_cache_pool;
|
||||
};
|
||||
|
||||
exceptions
|
||||
==========
|
||||
|
||||
@@ -362,65 +103,7 @@ error code on errors.
|
||||
There is one exception class that is used for errors in libtorrent, it is based
|
||||
on boost.system's ``error_code`` class to carry the error code.
|
||||
|
||||
libtorrent_exception
|
||||
--------------------
|
||||
|
||||
::
|
||||
|
||||
struct libtorrent_exception: std::exception
|
||||
{
|
||||
libtorrent_exception(error_code const& s);
|
||||
virtual const char* what() const throw();
|
||||
virtual ~libtorrent_exception() throw() {}
|
||||
boost::system::error_code error() const;
|
||||
};
|
||||
|
||||
|
||||
error_code
|
||||
==========
|
||||
|
||||
The names of these error codes are declared in then ``libtorrent::errors`` namespace.
|
||||
|
||||
HTTP errors are reported in the ``libtorrent::http_category``, with error code enums in
|
||||
the ``libtorrent::errors`` namespace.
|
||||
|
||||
====== =========================================
|
||||
code symbol
|
||||
====== =========================================
|
||||
100 cont
|
||||
------ -----------------------------------------
|
||||
200 ok
|
||||
------ -----------------------------------------
|
||||
201 created
|
||||
------ -----------------------------------------
|
||||
202 accepted
|
||||
------ -----------------------------------------
|
||||
204 no_content
|
||||
------ -----------------------------------------
|
||||
300 multiple_choices
|
||||
------ -----------------------------------------
|
||||
301 moved_permanently
|
||||
------ -----------------------------------------
|
||||
302 moved_temporarily
|
||||
------ -----------------------------------------
|
||||
304 not_modified
|
||||
------ -----------------------------------------
|
||||
400 bad_request
|
||||
------ -----------------------------------------
|
||||
401 unauthorized
|
||||
------ -----------------------------------------
|
||||
403 forbidden
|
||||
------ -----------------------------------------
|
||||
404 not_found
|
||||
------ -----------------------------------------
|
||||
500 internal_server_error
|
||||
------ -----------------------------------------
|
||||
501 not_implemented
|
||||
------ -----------------------------------------
|
||||
502 bad_gateway
|
||||
------ -----------------------------------------
|
||||
503 service_unavailable
|
||||
====== =========================================
|
||||
For more information, see libtorrent_exception and error_code_enum.
|
||||
|
||||
translating error codes
|
||||
-----------------------
|
||||
@@ -474,64 +157,6 @@ Here's a simple example of how to translate error codes::
|
||||
storage_interface
|
||||
=================
|
||||
|
||||
The storage interface is a pure virtual class that can be implemented to
|
||||
customize how and where data for a torrent is stored. The default storage
|
||||
implementation uses regular files in the filesystem, mapping the files in the
|
||||
torrent in the way one would assume a torrent is saved to disk. Implementing
|
||||
your own storage interface makes it possible to store all data in RAM, or in
|
||||
some optimized order on disk (the order the pieces are received for instance),
|
||||
or saving multifile torrents in a single file in order to be able to take
|
||||
advantage of optimized disk-I/O.
|
||||
|
||||
It is also possible to write a thin class that uses the default storage but
|
||||
modifies some particular behavior, for instance encrypting the data before
|
||||
it's written to disk, and decrypting it when it's read again.
|
||||
|
||||
The storage interface is based on slots, each slot is 'piece_size' number
|
||||
of bytes. All access is done by writing and reading whole or partial
|
||||
slots. One slot is one piece in the torrent, but the data in the slot
|
||||
does not necessarily correspond to the piece with the same index (in
|
||||
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_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.
|
||||
|
||||
|
||||
The interface looks like this::
|
||||
|
||||
struct storage_interface
|
||||
{
|
||||
virtual bool initialize(bool allocate_files) = 0;
|
||||
virtual bool has_any_file() = 0;
|
||||
virtual void hint_read(int slot, int offset, int len);
|
||||
virtual int readv(file::iovec_t const* bufs, int slot, int offset, int num_bufs) = 0;
|
||||
virtual int writev(file::iovec_t const* bufs, int slot, int offset, int num_bufs) = 0;
|
||||
virtual int sparse_end(int start) const;
|
||||
virtual bool move_storage(fs::path save_path) = 0;
|
||||
virtual bool verify_resume_data(lazy_entry const& rd, error_code& error) = 0;
|
||||
virtual bool write_resume_data(entry& rd) const = 0;
|
||||
virtual bool move_slot(int src_slot, int dst_slot) = 0;
|
||||
virtual bool swap_slots(int slot1, int slot2) = 0;
|
||||
virtual bool swap_slots3(int slot1, int slot2, int slot3) = 0;
|
||||
virtual bool rename_file(int file, std::string const& new_name) = 0;
|
||||
virtual bool release_files() = 0;
|
||||
virtual bool delete_files() = 0;
|
||||
virtual void finalize_file(int index) {}
|
||||
virtual ~storage_interface() {}
|
||||
|
||||
// non virtual functions
|
||||
|
||||
disk_buffer_pool* disk_pool();
|
||||
void set_error(std::string const& file, error_code const& ec) const;
|
||||
error_code const& error() const;
|
||||
std::string const& error_file() const;
|
||||
void clear_error();
|
||||
};
|
||||
|
||||
|
||||
initialize()
|
||||
------------
|
||||
|
||||
|
||||
Reference in New Issue
Block a user