diff --git a/docs/gen_reference_doc.py b/docs/gen_reference_doc.py index 320468c1f..037a51285 100644 --- a/docs/gen_reference_doc.py +++ b/docs/gen_reference_doc.py @@ -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() diff --git a/docs/manual.rst b/docs/manual.rst index cd1dccd3c..351eda318 100644 --- a/docs/manual.rst +++ b/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 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() ------------ diff --git a/include/libtorrent/add_torrent_params.hpp b/include/libtorrent/add_torrent_params.hpp index ed052c789..9a104d4b4 100644 --- a/include/libtorrent/add_torrent_params.hpp +++ b/include/libtorrent/add_torrent_params.hpp @@ -248,11 +248,11 @@ namespace libtorrent // The optional parameter, ``resume_data`` can be given if up to date fast-resume data // is available. The fast-resume data can be acquired from a running torrent by calling - // save_resume_data() on `torrent_handle`_. See `fast resume`_. The ``vector`` that is + // save_resume_data() on `torrent_handle`_. See fast-resume_. The ``vector`` that is // passed in will be swapped into the running torrent instance with ``std::vector::swap()``. std::vector resume_data; - // One of the values from storage_mode_t. For more information, see `storage allocation`_. + // One of the values from storage_mode_t. For more information, see storage-allocation_. storage_mode_t storage_mode; // can be used to customize how the data is stored. The default diff --git a/include/libtorrent/error_code.hpp b/include/libtorrent/error_code.hpp index c7b92b597..11b3110d7 100644 --- a/include/libtorrent/error_code.hpp +++ b/include/libtorrent/error_code.hpp @@ -430,6 +430,8 @@ namespace libtorrent error_code_max }; + // HTTP errors are reported in the libtorrent::http_category, with error code enums in + // the ``libtorrent::errors`` namespace. enum http_errors { cont = 100, diff --git a/include/libtorrent/magnet_uri.hpp b/include/libtorrent/magnet_uri.hpp index 42a0fca48..4eed27755 100644 --- a/include/libtorrent/magnet_uri.hpp +++ b/include/libtorrent/magnet_uri.hpp @@ -46,7 +46,7 @@ namespace libtorrent // Generates a magnet URI from the specified torrent. If the torrent // handle is invalid, an empty string is returned. // - // For more information about magnet links, see `magnet links`_. + // For more information about magnet links, see magnet-links_. // std::string TORRENT_EXPORT make_magnet_uri(torrent_handle const& handle); std::string TORRENT_EXPORT make_magnet_uri(torrent_info const& info); diff --git a/include/libtorrent/peer_info.hpp b/include/libtorrent/peer_info.hpp index dbc436a3b..14cb70ccc 100644 --- a/include/libtorrent/peer_info.hpp +++ b/include/libtorrent/peer_info.hpp @@ -192,6 +192,8 @@ namespace libtorrent // the IP-address to this peer. The type is an asio endpoint. For // more info, see the asio_ documentation. + // + // .. _asio: http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html tcp::endpoint ip; // the current upload and download speed diff --git a/include/libtorrent/session.hpp b/include/libtorrent/session.hpp index 12384e0c5..64bc38db6 100644 --- a/include/libtorrent/session.hpp +++ b/include/libtorrent/session.hpp @@ -689,7 +689,7 @@ namespace libtorrent // These functions sets and queries the proxy settings to be used for the session. // // For more information on what settings are available for proxies, see - // `proxy_settings`_. + // proxy_settings. void set_proxy(proxy_settings const& s); proxy_settings proxy() const; @@ -854,7 +854,7 @@ namespace libtorrent // The upnp object returned by ``start_upnp()`` can be used to add and remove // arbitrary port mappings. Mapping status is returned through the // portmap_alert and the portmap_error_alert. The object will be valid until - // ``stop_upnp()`` is called. See `UPnP and NAT-PMP`_. + // ``stop_upnp()`` is called. See upnp-and-nat-pmp_. // // It is off by default. void start_upnp(); @@ -866,7 +866,7 @@ namespace libtorrent // The natpmp object returned by ``start_natpmp()`` can be used to add and remove // arbitrary port mappings. Mapping status is returned through the // portmap_alert and the portmap_error_alert. The object will be valid until - // ``stop_natpmp()`` is called. See `UPnP and NAT-PMP`_. + // ``stop_natpmp()`` is called. See upnp-and-nat-pmp_. // // It is off by default. void start_natpmp(); diff --git a/include/libtorrent/session_settings.hpp b/include/libtorrent/session_settings.hpp index b5ba669ba..a9ae56bb1 100644 --- a/include/libtorrent/session_settings.hpp +++ b/include/libtorrent/session_settings.hpp @@ -378,9 +378,9 @@ namespace libtorrent // are kept in memory after the torrent becomes a seed or not. If it is set to // ``true`` the hashes are freed once the torrent is a seed (they're not // needed anymore since the torrent won't download anything more). If it's set - // to false they are not freed. If they are freed, the torrent_info_ returned + // to false they are not freed. If they are freed, the torrent_info returned // by get_torrent_info() will return an object that may be incomplete, that - // cannot be passed back to `async_add_torrent() add_torrent()`_ for instance. + // cannot be passed back to async_add_torrent() and add_torrent() for instance. bool free_torrent_hashes; // indicates whether or not the UPnP implementation @@ -798,7 +798,7 @@ namespace libtorrent int max_sparse_regions; #ifndef TORRENT_DISABLE_MLOCK - // if lock disk cache is set to true the disk cache + // if lock disk cache is set to true the disk cache // that's in use, will be locked in physical memory, preventing it from // being swapped out. bool lock_disk_cache; diff --git a/include/libtorrent/storage.hpp b/include/libtorrent/storage.hpp index b9043748e..aee4b6f91 100644 --- a/include/libtorrent/storage.hpp +++ b/include/libtorrent/storage.hpp @@ -99,6 +99,30 @@ namespace libtorrent hasher h; }; + // 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. struct TORRENT_EXPORT storage_interface { storage_interface(): m_disk_pool(0), m_settings(0) {} diff --git a/include/libtorrent/torrent_handle.hpp b/include/libtorrent/torrent_handle.hpp index faabc2281..9b7386860 100644 --- a/include/libtorrent/torrent_handle.hpp +++ b/include/libtorrent/torrent_handle.hpp @@ -404,15 +404,15 @@ namespace libtorrent // currently in this torrent. Note that urls that fails may be removed // automatically from the list. // - // See `HTTP seeding`_ for more information. + // See http-seeding_ for more information. void add_url_seed(std::string const& url) const; void remove_url_seed(std::string const& url) const; std::set url_seeds() const; // These functions are identical as the ``*_url_seed()`` variants, but they - // operate on BEP 17 web seeds instead of BEP 19. + // operate on `BEP 17`_ web seeds instead of `BEP 19`_. // - // See `HTTP seeding`_ for more information. + // See http-seeding_ for more information. void add_http_seed(std::string const& url) const; void remove_http_seed(std::string const& url) const; std::set http_seeds() const; @@ -498,7 +498,7 @@ namespace libtorrent enum save_resume_flags_t { flush_disk_cache = 1, 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`_. + // 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 @@ -517,7 +517,7 @@ namespace libtorrent // 2. The torrent is checking (or is queued for checking) its storage, it will obviously // not be ready to write resume data. // 3. The torrent hasn't received valid metadata and was started without metadata - // (see libtorrent's `metadata from peers`_ extension) + // (see libtorrent's metadata-from-peers_ extension) // // Note that by the time you receive the fast resume data, it may already be invalid if the torrent // is still downloading! The recommended practice is to first pause the session, then generate the @@ -1312,7 +1312,7 @@ namespace libtorrent int connections_limit; // The allocation mode for the torrent. See storage_mode_t for the options. - // For more information, see `Storage allocation`_. + // For more information, see storage-allocation_. storage_mode_t storage_mode; // the number of peers in this diff --git a/include/libtorrent/torrent_info.hpp b/include/libtorrent/torrent_info.hpp index 5b8733c25..93c524870 100644 --- a/include/libtorrent/torrent_info.hpp +++ b/include/libtorrent/torrent_info.hpp @@ -414,7 +414,7 @@ namespace libtorrent // The ``extra_headers`` argument defaults to an empty list, but can be used to // insert custom HTTP headers in the requests to a specific web seed. // - // See `HTTP seeding`_ for more information. + // See http-seeding_ for more information. void add_url_seed(std::string const& url , std::string const& extern_auth = std::string() , web_seed_entry::headers_t const& extra_headers = web_seed_entry::headers_t());