diff --git a/docs/gen_reference_doc.py b/docs/gen_reference_doc.py index 9794e6959..320468c1f 100644 --- a/docs/gen_reference_doc.py +++ b/docs/gen_reference_doc.py @@ -576,11 +576,18 @@ for c in classes: for f in c['fun']: for n in f['names']: symbols[n] = filename + n + symbols[c['name'] + '::' + n] = filename + n + + for f in c['fields']: + for n in f['names']: + symbols[c['name'] + '::' + n] = filename + n for e in c['enums']: symbols[e['name']] = filename + e['name'] for v in e['values']: - symbols[v['name']] = filename + v['name'] +# symbols[v['name']] = filename + v['name'] + symbols[e['name'] + '::' + v['name']] = filename + v['name'] + symbols[c['name'] + '::' + v['name']] = filename + v['name'] for f in functions: cat = categorize_symbol(first_item(f['names']), f['file']) @@ -599,7 +606,10 @@ for e in enums: if not cat in categories: categories[cat] = { 'classes': [], 'functions': [], 'enums': [], 'filename': 'reference-%s.rst' % cat.replace(' ', '_')} categories[cat]['enums'].append(e) - symbols[e['name']] = categories[cat]['filename'].replace('.rst', '.html') + '#' + e['name'] + filename = categories[cat]['filename'].replace('.rst', '.html') + '#' + symbols[e['name']] = filename + e['name'] + for v in e['values']: + symbols[e['name'] + '::' + v['name']] = filename + v['name'] def print_declared_in(out, o): out.write('Declared in "%s"\n\n' % print_link(o['file'], '../include/%s' % o['file'])) diff --git a/docs/manual.rst b/docs/manual.rst index a4b3ccb5e..2a0b68623 100644 --- a/docs/manual.rst +++ b/docs/manual.rst @@ -1268,1315 +1268,6 @@ disabled by default. Enabling it makes the cache perform better at high throughp It also makes the cache less likely and slower at returning memory back to the system once allocated. -torrent_added_alert -------------------- - -The ``torrent_added_alert`` is posted once every time a torrent is successfully -added. It doesn't contain any members of its own, but inherits the torrent handle -from its base class. -It's posted when the ``status_notification`` bit is set in the alert mask. - -:: - - struct torrent_added_alert: torrent_alert - { - // ... - }; - - -add_torrent_alert ------------------ - -This alert is always posted when a torrent was attempted to be added -and contains the return status of the add operation. The torrent handle of the new -torrent can be found in the base class' ``handle`` member. If adding -the torrent failed, ``error`` contains the error code. - -:: - - struct add_torrent_alert: torrent_alert - { - // ... - add_torrent_params params; - error_code error; - }; - -``params`` is a copy of the parameters used when adding the torrent, it can be used -to identify which invocation to ``async_add_torrent()`` caused this alert. - -``error`` is set to the error, if one occurred while adding the torrent. - - -torrent_removed_alert ---------------------- - -The ``torrent_removed_alert`` is posted whenever a torrent is removed. Since -the torrent handle in its baseclass will always be invalid (since the torrent -is already removed) it has the info hash as a member, to identify it. -It's posted when the ``status_notification`` bit is set in the alert mask. - -Even though the ``handle`` member doesn't point to an existing torrent anymore, -it is still useful for comparing to other handles, which may also no -longer point to existing torrents, but to the same non-existing torrents. - -The ``torrent_handle`` acts as a ``weak_ptr``, even though its object no -longer exists, it can still compare equal to another weak pointer which -points to the same non-existent object. - -:: - - struct torrent_removed_alert: torrent_alert - { - // ... - sha1_hash info_hash; - }; - -read_piece_alert ----------------- - -This alert is posted when the asynchronous read operation initiated by -a call to `read_piece()`_ is completed. If the read failed, the torrent -is paused and an error state is set and the buffer member of the alert -is 0. If successful, ``buffer`` points to a buffer containing all the data -of the piece. ``piece`` is the piece index that was read. ``size`` is the -number of bytes that was read. - -If the operation fails, ec will indicat what went wrong. - -:: - - struct read_piece_alert: torrent_alert - { - // ... - error_code ec; - boost::shared_ptr buffer; - int piece; - int size; - }; - -external_ip_alert ------------------ - -Whenever libtorrent learns about the machines external IP, this alert is -generated. The external IP address can be acquired from the tracker (if it -supports that) or from peers that supports the extension protocol. -The address can be accessed through the ``external_address`` member. - -:: - - struct external_ip_alert: alert - { - // ... - address external_address; - }; - - -listen_failed_alert -------------------- - -This alert is generated when none of the ports, given in the port range, to -session_ can be opened for listening. The ``endpoint`` member is the -interface and port that failed, ``error`` is the error code describing -the failure. - -libtorrent may sometimes try to listen on port 0, if all other ports failed. -Port 0 asks the operating system to pick a port that's free). If that fails -you may see a listen_failed_alert_ with port 0 even if you didn't ask to -listen on it. - -:: - - struct listen_failed_alert: alert - { - // ... - tcp::endpoint endpoint; - error_code error; - }; - -listen_succeeded_alert ----------------------- - -This alert is posted when the listen port succeeds to be opened on a -particular interface. ``endpoint`` is the endpoint that successfully -was opened for listening. - -:: - - struct listen_succeeded_alert: alert - { - // ... - tcp::endpoint endpoint; - }; - - -portmap_error_alert -------------------- - -This alert is generated when a NAT router was successfully found but some -part of the port mapping request failed. It contains a text message that -may help the user figure out what is wrong. This alert is not generated in -case it appears the client is not running on a NAT:ed network or if it -appears there is no NAT router that can be remote controlled to add port -mappings. - -``mapping`` refers to the mapping index of the port map that failed, i.e. -the index returned from `add_mapping()`_. - -``map_type`` is 0 for NAT-PMP and 1 for UPnP. - -``error`` tells you what failed. -:: - - struct portmap_error_alert: alert - { - // ... - int mapping; - int type; - error_code error; - }; - -portmap_alert -------------- - -This alert is generated when a NAT router was successfully found and -a port was successfully mapped on it. On a NAT:ed network with a NAT-PMP -capable router, this is typically generated once when mapping the TCP -port and, if DHT is enabled, when the UDP port is mapped. - -``mapping`` refers to the mapping index of the port map that failed, i.e. -the index returned from `add_mapping()`_. - -``external_port`` is the external port allocated for the mapping. - -``type`` is 0 for NAT-PMP and 1 for UPnP. - -:: - - struct portmap_alert: alert - { - // ... - int mapping; - int external_port; - int map_type; - }; - -portmap_log_alert ------------------ - -This alert is generated to log informational events related to either -UPnP or NAT-PMP. They contain a log line and the type (0 = NAT-PMP -and 1 = UPnP). Displaying these messages to an end user is only useful -for debugging the UPnP or NAT-PMP implementation. - -:: - - struct portmap_log_alert: alert - { - //... - int map_type; - std::string msg; - }; - -file_error_alert ----------------- - -If the storage fails to read or write files that it needs access to, this alert is -generated and the torrent is paused. - -``file`` is the path to the file that was accessed when the error occurred. - -``error`` is the error code describing the error. - -:: - - struct file_error_alert: torrent_alert - { - // ... - std::string file; - error_code error; - }; - -torrent_error_alert -------------------- - -This is posted whenever a torrent is transitioned into the error state. - -:: - - struct torrent_error_alert: torrent_alert - { - // ... - error_code error; - }; - -The ``error`` specifies which error the torrent encountered. - -file_renamed_alert ------------------- - -This is posted as a response to a ``torrent_handle::rename_file`` call, if the rename -operation succeeds. - -:: - - struct file_renamed_alert: torrent_alert - { - // ... - std::string name; - int index; - }; - -The ``index`` member refers to the index of the file that was renamed, -``name`` is the new name of the file. - - -file_rename_failed_alert ------------------------- - -This is posted as a response to a ``torrent_handle::rename_file`` call, if the rename -operation failed. - -:: - - struct file_rename_failed_alert: torrent_alert - { - // ... - int index; - error_code error; - }; - -The ``index`` member refers to the index of the file that was supposed to be renamed, -``error`` is the error code returned from the filesystem. - -tracker_announce_alert ----------------------- - -This alert is generated each time a tracker announce is sent (or attempted to be sent). -There are no extra data members in this alert. The url can be found in the base class -however. - -:: - - struct tracker_announce_alert: tracker_alert - { - // ... - int event; - }; - -Event specifies what event was sent to the tracker. It is defined as: - -0. None -1. Completed -2. Started -3. Stopped - - -tracker_error_alert -------------------- - -This alert is generated on tracker time outs, premature disconnects, invalid response or -a HTTP response other than "200 OK". From the alert you can get the handle to the torrent -the tracker belongs to. - -The ``times_in_row`` member says how many times in a row this tracker has failed. -``status_code`` is the code returned from the HTTP server. 401 means the tracker needs -authentication, 404 means not found etc. If the tracker timed out, the code will be set -to 0. - -:: - - struct tracker_error_alert: tracker_alert - { - // ... - int times_in_row; - int status_code; - }; - - -tracker_reply_alert -------------------- - -This alert is only for informational purpose. It is generated when a tracker announce -succeeds. It is generated regardless what kind of tracker was used, be it UDP, HTTP or -the DHT. - -:: - - struct tracker_reply_alert: tracker_alert - { - // ... - int num_peers; - }; - -The ``num_peers`` tells how many peers the tracker returned in this response. This is -not expected to be more thant the ``num_want`` settings. These are not necessarily -all new peers, some of them may already be connected. - -tracker_warning_alert ---------------------- - -This alert is triggered if the tracker reply contains a warning field. Usually this -means that the tracker announce was successful, but the tracker has a message to -the client. The ``msg`` string in the alert contains the warning message from -the tracker. - -:: - - struct tracker_warning_alert: tracker_alert - { - // ... - std::string msg; - }; - -scrape_reply_alert ------------------- - -This alert is generated when a scrape request succeeds. ``incomplete`` -and ``complete`` is the data returned in the scrape response. These numbers -may be -1 if the reponse was malformed. - -:: - - struct scrape_reply_alert: tracker_alert - { - // ... - int incomplete; - int complete; - }; - - -scrape_failed_alert -------------------- - -If a scrape request fails, this alert is generated. This might be due -to the tracker timing out, refusing connection or returning an http response -code indicating an error. ``msg`` contains a message describing the error. - -:: - - struct scrape_failed_alert: tracker_alert - { - // ... - std::string msg; - }; - -url_seed_alert --------------- - -This alert is generated when a HTTP seed name lookup fails. - -It contains ``url`` to the HTTP seed that failed along with an error message. - -:: - - struct url_seed_alert: torrent_alert - { - // ... - std::string url; - }; - - -hash_failed_alert ------------------ - -This alert is generated when a finished piece fails its hash check. You can get the handle -to the torrent which got the failed piece and the index of the piece itself from the alert. - -:: - - struct hash_failed_alert: torrent_alert - { - // ... - int piece_index; - }; - - -peer_alert ----------- - -The peer alert is a base class for alerts that refer to a specific peer. It includes all -the information to identify the peer. i.e. ``ip`` and ``peer-id``. - -:: - - struct peer_alert: torrent_alert - { - // ... - tcp::endpoint ip; - peer_id pid; - }; - -peer_connect_alert ------------------- - -This alert is posted every time an outgoing peer connect attempts succeeds. - -:: - - struct peer_connect_alert: peer_alert - { - // ... - }; - -peer_ban_alert --------------- - -This alert is generated when a peer is banned because it has sent too many corrupt pieces -to us. ``ip`` is the endpoint to the peer that was banned. - -:: - - struct peer_ban_alert: peer_alert - { - // ... - }; - - -peer_snubbed_alert ------------------- - -This alert is generated when a peer is snubbed, when it stops sending data when we request -it. - -:: - - struct peer_snubbed_alert: peer_alert - { - // ... - }; - - -peer_unsnubbed_alert --------------------- - -This alert is generated when a peer is unsnubbed. Essentially when it was snubbed for stalling -sending data, and now it started sending data again. - -:: - - struct peer_unsnubbed_alert: peer_alert - { - // ... - }; - - -peer_error_alert ----------------- - -This alert is generated when a peer sends invalid data over the peer-peer protocol. The peer -will be disconnected, but you get its ip address from the alert, to identify it. - -The ``error_code`` tells you what error caused this alert. - -:: - - struct peer_error_alert: peer_alert - { - // ... - error_code error; - }; - - -peer_connected_alert --------------------- - -This alert is generated when a peer is connected. - -:: - - struct peer_connected_alert: peer_alert - { - // ... - }; - - -peer_disconnected_alert ------------------------ - -This alert is generated when a peer is disconnected for any reason (other than the ones -covered by ``peer_error_alert``). - -The ``error_code`` tells you what error caused peer to disconnect. - -:: - - struct peer_disconnected_alert: peer_alert - { - // ... - error_code error; - }; - - -invalid_request_alert ---------------------- - -This is a debug alert that is generated by an incoming invalid piece request. -``ip`` is the address of the peer and the ``request`` is the actual incoming -request from the peer. - -:: - - struct invalid_request_alert: peer_alert - { - // ... - peer_request request; - }; - - - struct peer_request - { - int piece; - int start; - int length; - bool operator==(peer_request const& r) const; - }; - - -The ``peer_request`` contains the values the client sent in its ``request`` message. ``piece`` is -the index of the piece it want data from, ``start`` is the offset within the piece where the data -should be read, and ``length`` is the amount of data it wants. - -request_dropped_alert ---------------------- - -This alert is generated when a peer rejects or ignores a piece request. - -:: - - struct request_dropped_alert: peer_alert - { - // ... - int block_index; - int piece_index; - }; - - -block_timeout_alert -------------------- - -This alert is generated when a block request times out. - -:: - - struct block_timeout_alert: peer_alert - { - // ... - int block_index; - int piece_index; - }; - - -block_finished_alert --------------------- - -This alert is generated when a block request receives a response. - -:: - - struct block_finished_alert: peer_alert - { - // ... - int block_index; - int piece_index; - }; - - -lsd_peer_alert --------------- - -This alert is generated when we receive a local service discovery message from a peer -for a torrent we're currently participating in. - -:: - - struct lsd_peer_alert: peer_alert - { - // ... - }; - - -file_completed_alert --------------------- - -This is posted whenever an individual file completes its download. i.e. -All pieces overlapping this file have passed their hash check. - -:: - - struct file_completed_alert: torrent_alert - { - // ... - int index; - }; - -The ``index`` member refers to the index of the file that completed. - - -block_downloading_alert ------------------------ - -This alert is generated when a block request is sent to a peer. - -:: - - struct block_downloading_alert: peer_alert - { - // ... - int block_index; - int piece_index; - }; - - -unwanted_block_alert --------------------- - -This alert is generated when a block is received that was not requested or -whose request timed out. - -:: - - struct unwanted_block_alert: peer_alert - { - // ... - int block_index; - int piece_index; - }; - - -torrent_delete_failed_alert ---------------------------- - -This alert is generated when a request to delete the files of a torrent fails. - -The ``error_code`` tells you why it failed. - -:: - - struct torrent_delete_failed_alert: torrent_alert - { - // ... - error_code error; - }; - -torrent_deleted_alert ---------------------- - -This alert is generated when a request to delete the files of a torrent complete. - -The ``info_hash`` is the info-hash of the torrent that was just deleted. Most of -the time the torrent_handle in the ``torrent_alert`` will be invalid by the time -this alert arrives, since the torrent is being deleted. The ``info_hash`` member -is hence the main way of identifying which torrent just completed the delete. - -This alert is posted in the ``storage_notification`` category, and that bit -needs to be set in the alert mask. - -:: - - struct torrent_deleted_alert: torrent_alert - { - // ... - sha1_hash info_hash; - }; - -torrent_finished_alert ----------------------- - -This alert is generated when a torrent switches from being a downloader to a seed. -It will only be generated once per torrent. It contains a torrent_handle to the -torrent in question. - -There are no additional data members in this alert. - - -performance_alert ------------------ - -This alert is generated when a limit is reached that might have a negative impact on -upload or download rate performance. - -:: - - struct performance_alert: torrent_alert - { - // ... - - enum performance_warning_t - { - outstanding_disk_buffer_limit_reached, - outstanding_request_limit_reached, - upload_limit_too_low, - download_limit_too_low, - send_buffer_watermark_too_low, - too_many_optimistic_unchoke_slots, - too_high_disk_queue_limit, - too_few_outgoing_ports - }; - - performance_warning_t warning_code; - }; - -outstanding_disk_buffer_limit_reached - This warning means that the number of bytes queued to be written to disk - exceeds the max disk byte queue setting (``session_settings::max_queued_disk_bytes``). - This might restrict the download rate, by not queuing up enough write jobs - to the disk I/O thread. When this alert is posted, peer connections are - temporarily stopped from downloading, until the queued disk bytes have fallen - below the limit again. Unless your ``max_queued_disk_bytes`` setting is already - high, you might want to increase it to get better performance. - -outstanding_request_limit_reached - This is posted when libtorrent would like to send more requests to a peer, - but it's limited by ``session_settings::max_out_request_queue``. The queue length - libtorrent is trying to achieve is determined by the download rate and the - assumed round-trip-time (``session_settings::request_queue_time``). The assumed - rount-trip-time is not limited to just the network RTT, but also the remote disk - access time and message handling time. It defaults to 3 seconds. The target number - of outstanding requests is set to fill the bandwidth-delay product (assumed RTT - times download rate divided by number of bytes per request). When this alert - is posted, there is a risk that the number of outstanding requests is too low - and limits the download rate. You might want to increase the ``max_out_request_queue`` - setting. - -upload_limit_too_low - This warning is posted when the amount of TCP/IP overhead is greater than the - upload rate limit. When this happens, the TCP/IP overhead is caused by a much - faster download rate, triggering TCP ACK packets. These packets eat into the - rate limit specified to libtorrent. When the overhead traffic is greater than - the rate limit, libtorrent will not be able to send any actual payload, such - as piece requests. This means the download rate will suffer, and new requests - can be sent again. There will be an equilibrium where the download rate, on - average, is about 20 times the upload rate limit. If you want to maximize the - download rate, increase the upload rate limit above 5% of your download capacity. - -download_limit_too_low - This is the same warning as ``upload_limit_too_low`` but referring to the download - limit instead of upload. This suggests that your download rate limit is mcuh lower - than your upload capacity. Your upload rate will suffer. To maximize upload rate, - make sure your download rate limit is above 5% of your upload capacity. - -send_buffer_watermark_too_low - We're stalled on the disk. We want to write to the socket, and we can write - but our send buffer is empty, waiting to be refilled from the disk. - This either means the disk is slower than the network connection - or that our send buffer watermark is too small, because we can - send it all before the disk gets back to us. - The number of bytes that we keep outstanding, requested from the disk, is calculated - as follows:: - - min(512, max(upload_rate * send_buffer_watermark_factor / 100, send_buffer_watermark)) - - If you receive this alert, you migth want to either increase your ``send_buffer_watermark`` - or ``send_buffer_watermark_factor``. - -too_many_optimistic_unchoke_slots - If the half (or more) of all upload slots are set as optimistic unchoke slots, this - warning is issued. You probably want more regular (rate based) unchoke slots. - -too_high_disk_queue_limit - If the disk write queue ever grows larger than half of the cache size, this warning - is posted. The disk write queue eats into the total disk cache and leaves very little - left for the actual cache. This causes the disk cache to oscillate in evicting large - portions of the cache before allowing peers to download any more, onto the disk write - queue. Either lower ``max_queued_disk_bytes`` or increase ``cache_size``. - -too_few_outgoing_ports - This is generated if outgoing peer connections are failing because of *address in use* - errors, indicating that ``session_settings::outgoing_ports`` is set and is too small of - a range. Consider not using the ``outgoing_ports`` setting at all, or widen the range to - include more ports. - -state_changed_alert -------------------- - -Generated whenever a torrent changes its state. - -:: - - struct state_changed_alert: torrent_alert - { - // ... - - torrent_status::state_t state; - torrent_status::state_t prev_state; - }; - -``state`` is the new state of the torrent. ``prev_state`` is the previous state. - - -metadata_failed_alert ---------------------- - -This alert is generated when the metadata has been completely received and the info-hash -failed to match it. i.e. the metadata that was received was corrupt. libtorrent will -automatically retry to fetch it in this case. This is only relevant when running a -torrent-less download, with the metadata extension provided by libtorrent. - -There are no additional data members in this alert. - - -metadata_received_alert ------------------------ - -This alert is generated when the metadata has been completely received and the torrent -can start downloading. It is not generated on torrents that are started with metadata, but -only those that needs to download it from peers (when utilizing the libtorrent extension). - -There are no additional data members in this alert. - -Typically, when receiving this alert, you would want to save the torrent file in order -to load it back up again when the session is restarted. Here's an example snippet of -code to do that:: - - torrent_handle h = alert->handle(); - if (h.is_valid()) { - boost::intrusive_ptr ti = h.torrent_file(); - create_torrent ct(*ti); - entry te = ct.generate(); - std::vector buffer; - bencode(std::back_inserter(buffer), te); - FILE* f = fopen((to_hex(ti->info_hash().to_string()) + ".torrent").c_str(), "wb+"); - if (f) { - fwrite(&buffer[0], 1, buffer.size(), f); - fclose(f); - } - } - -fastresume_rejected_alert -------------------------- - -This alert is generated when a fastresume file has been passed to ``add_torrent`` but the -files on disk did not match the fastresume file. The ``error_code`` explains the reason why the -resume file was rejected. - -:: - - struct fastresume_rejected_alert: torrent_alert - { - // ... - error_code error; - }; - - -peer_blocked_alert ------------------- - -This alert is posted when an incoming peer connection, or a peer that's about to be added -to our peer list, is blocked for some reason. This could be any of: - -* the IP filter -* i2p mixed mode restrictions (a normal peer is not allowed on an i2p swarm) -* the port filter -* the peer has a low port and ``no_connect_privileged_ports`` is enabled -* the protocol of the peer is blocked (uTP/TCP blocking) - -The ``ip`` member is the address that was blocked. - -:: - - struct peer_blocked_alert: torrent_alert - { - // ... - address ip; - }; - - -storage_moved_alert -------------------- - -The ``storage_moved_alert`` is generated when all the disk IO has completed and the -files have been moved, as an effect of a call to ``torrent_handle::move_storage``. This -is useful to synchronize with the actual disk. The ``path`` member is the new path of -the storage. - -:: - - struct storage_moved_alert: torrent_alert - { - // ... - std::string path; - }; - - -storage_moved_failed_alert --------------------------- - -The ``storage_moved_failed_alert`` is generated when an attempt to move the storage -(via torrent_handle::move_storage()) fails. - -:: - - struct storage_moved_failed_alert: torrent_alert - { - // ... - error_code error; - }; - - -torrent_paused_alert --------------------- - -This alert is generated as a response to a ``torrent_handle::pause`` request. It is -generated once all disk IO is complete and the files in the torrent have been closed. -This is useful for synchronizing with the disk. - -There are no additional data members in this alert. - -torrent_resumed_alert ---------------------- - -This alert is generated as a response to a ``torrent_handle::resume`` request. It is -generated when a torrent goes from a paused state to an active state. - -There are no additional data members in this alert. - -save_resume_data_alert ----------------------- - -This alert is generated as a response to a ``torrent_handle::save_resume_data`` request. -It is generated once the disk IO thread is done writing the state for this torrent. -The ``resume_data`` member points to the resume data. - -:: - - struct save_resume_data_alert: torrent_alert - { - // ... - boost::shared_ptr resume_data; - }; - -save_resume_data_failed_alert ------------------------------ - -This alert is generated instead of ``save_resume_data_alert`` if there was an error -generating the resume data. ``error`` describes what went wrong. - -:: - - struct save_resume_data_failed_alert: torrent_alert - { - // ... - error_code error; - }; - -stats_alert ------------ - -This alert is posted approximately once every second, and it contains -byte counters of most statistics that's tracked for torrents. Each active -torrent posts these alerts regularly. - -:: - - struct stats_alert: torrent_alert - { - // ... - enum stats_channel - { - upload_payload, - upload_protocol, - upload_ip_protocol, - upload_dht_protocol, - upload_tracker_protocol, - download_payload, - download_protocol, - download_ip_protocol, - download_dht_protocol, - download_tracker_protocol, - num_channels - }; - - int transferred[num_channels]; - int interval; - }; - -``transferred`` this is an array of samples. The enum describes what each -sample is a measurement of. All of these are raw, and not smoothing is performed. - -``interval`` the number of milliseconds during which these stats -were collected. This is typically just above 1000, but if CPU is -limited, it may be higher than that. - - -cache_flushed_alert -------------------- - -This alert is posted when the disk cache has been flushed for a specific torrent -as a result of a call to `flush_cache()`_. This alert belongs to the -``storage_notification`` category, which must be enabled to let this alert through. -The alert is also posted when removing a torrent from the session, once the outstanding -cache flush is complete and the torrent does no longer have any files open. - -:: - - struct flush_cached_alert: torrent_alert - { - // ... - }; - -torrent_need_cert_alert ------------------------ - -This is always posted for SSL torrents. This is a reminder to the client that -the torrent won't work unless torrent_handle::set_ssl_certificate() is called with -a valid certificate. Valid certificates MUST be signed by the SSL certificate -in the .torrent file. - -:: - - struct torrent_need_cert_alert: tracker_alert - { - // ... - }; - -dht_announce_alert ------------------- - -This alert is generated when a DHT node announces to an info-hash on our DHT node. It belongs -to the ``dht_notification`` category. - -:: - - struct dht_announce_alert: alert - { - // ... - address ip; - int port; - sha1_hash info_hash; - }; - -dht_get_peers_alert -------------------- - -This alert is generated when a DHT node sends a ``get_peers`` message to our DHT node. -It belongs to the ``dht_notification`` category. - -:: - - struct dht_get_peers_alert: alert - { - // ... - sha1_hash info_hash; - }; - -dht_reply_alert ---------------- - -This alert is generated each time the DHT receives peers from a node. ``num_peers`` -is the number of peers we received in this packet. Typically these packets are -received from multiple DHT nodes, and so the alerts are typically generated -a few at a time. - -:: - - struct dht_reply_alert: tracker_alert - { - // ... - int num_peers; - }; - -dht_bootstrap_alert -------------------- - -This alert is posted when the initial DHT bootstrap is done. There's no any other -relevant information associated with this alert. - -:: - - struct dht_bootstrap_alert: alert - { - // ... - }; - -anonymous_mode_alert --------------------- - -This alert is posted when a bittorrent feature is blocked because of the -anonymous mode. For instance, if the tracker proxy is not set up, no -trackers will be used, because trackers can only be used through proxies -when in anonymous mode. - -:: - - struct anonymous_mode_alert: tracker_alert - { - // ... - enum kind_t - { - tracker_not_anonymous = 1 - }; - int kind; - std::string str; - }; - -``kind`` specifies what error this is, it's one of: - -``tracker_not_anonymous`` means that there's no proxy set up for tracker -communication and the tracker will not be contacted. The tracker which -this failed for is specified in the ``str`` member. - -rss_alert ---------- - -This alert is posted on RSS feed events such as start of RSS feed updates, -successful completed updates and errors during updates. - -This alert is only posted if the ``rss_notifications`` category is enabled -in the alert mask. - -:: - - struct rss_alert: alert - { - // .. - virtual std::string message() const; - - enum state_t - { - state_updating, state_updated, state_error - }; - - feed_handle handle; - std::string url; - int state; - error_code error; - }; - -``handle`` is the handle to the feed which generated this alert. - -``url`` is a short cut to access the url of the feed, without -having to call ``get_settings()``. - -``state`` is one of: - -``rss_alert::state_updating`` - An update of this feed was just initiated, it will either succeed - or fail soon. - -``rss_alert::state_updated`` - The feed just completed a successful update, there may be new items - in it. If you're adding torrents manually, you may want to request - the feed status of the feed and look through the ``items`` vector. - -``rss_akert::state_error`` - An error just occurred. See the ``error`` field for information on - what went wrong. - -``error`` is an error code used for when an error occurs on the feed. - -rss_item_alert --------------- - -This alert is posted every time a new RSS item (i.e. torrent) is received -from an RSS feed. - -It is only posted if the ``rss_notifications`` category is enabled in the -alert mask. - -:: - - struct rss_alert : alert - { - // ... - virtual std::string message() const; - - feed_handle handle; - feed_item item; - }; - -incoming_connection_alert -------------------------- - -The incoming connection alert is posted every time we successfully accept -an incoming connection, through any mean. The most straigh-forward ways -of accepting incoming connections are through the TCP listen socket and -the UDP listen socket for uTP sockets. However, connections may also be -accepted ofer a Socks5 or i2p listen socket, or via a torrent specific -listen socket for SSL torrents. - -:: - - struct incoming_connection_alert: alert - { - // ... - virtual std::string message() const; - - int socket_type; - tcp::endpoint ip; - }; - -``socket_type`` tells you what kind of socket the connection was accepted -as: - -+----------+-------------------------------------+ -| value | type | -+==========+=====================================+ -| 0 | none (no socket instantiated) | -+----------+-------------------------------------+ -| 1 | TCP | -+----------+-------------------------------------+ -| 2 | Socks5 | -+----------+-------------------------------------+ -| 3 | HTTP | -+----------+-------------------------------------+ -| 4 | uTP | -+----------+-------------------------------------+ -| 5 | i2p | -+----------+-------------------------------------+ -| 6 | SSL/TCP | -+----------+-------------------------------------+ -| 7 | SSL/Socks5 | -+----------+-------------------------------------+ -| 8 | HTTPS (SSL/HTTP) | -+----------+-------------------------------------+ -| 9 | SSL/uTP | -+----------+-------------------------------------+ - -``ip`` is the IP address and port the connection came from. - -state_update_alert ------------------- - -This alert is only posted when requested by the user, by calling `post_torrent_updates()`_ -on the session. It contains the torrent status of all torrents that changed -since last time this message was posted. Its category is ``status_notification``, but -it's not subject to filtering, since it's only manually posted anyway. - -:: - - - struct state_update_alert: alert - { - // ... - std::vector status; - }; - -``status`` contains the torrent status of all torrents that changed since last time -this message was posted. Note that you can map a torrent status to a specific torrent -via its ``handle`` member. The receiving end is suggested to have all torrents sorted -by the ``torrent_handle`` or hashed by it, for efficient updates. - -torrent_update_alert --------------------- - -When a torrent changes its info-hash, this alert is posted. This only happens in very -specific cases. For instance, when a torrent is downloaded from a URL, the true info -hash is not known immediately. First the .torrent file must be downloaded and parsed. - -Once this download completes, the ``torrent_update_alert`` is posted to notify the client -of the info-hash changing. - -:: - - struct torrent_update_alert: torrent_alert - { - // ... - sha1_hash old_ih; - sha1_hash new_ih; - }; - -``old_ih`` and ``new_ih`` are the previous and new info-hash for the torrent, respectively. - exceptions ========== diff --git a/include/libtorrent/alert_types.hpp b/include/libtorrent/alert_types.hpp index 69b99a70a..1a34e8960 100644 --- a/include/libtorrent/alert_types.hpp +++ b/include/libtorrent/alert_types.hpp @@ -69,13 +69,15 @@ namespace libtorrent torrent_handle handle; }; + // The peer alert is a base class for alerts that refer to a specific peer. It includes all + // the information to identify the peer. i.e. ``ip`` and ``peer-id``. struct TORRENT_EXPORT peer_alert: torrent_alert { - peer_alert(torrent_handle const& h, tcp::endpoint const& ip_ - , peer_id const& pid_) + peer_alert(torrent_handle const& h, tcp::endpoint const& i + , peer_id const& pi) : torrent_alert(h) - , ip(ip_) - , pid(pid_) + , ip(i) + , pid(pi) {} const static int alert_type = 2; @@ -90,9 +92,9 @@ namespace libtorrent struct TORRENT_EXPORT tracker_alert: torrent_alert { tracker_alert(torrent_handle const& h - , std::string const& url_) + , std::string const& u) : torrent_alert(h) - , url(url_) + , url(u) {} const static int alert_type = 3; @@ -111,6 +113,10 @@ namespace libtorrent virtual int category() const { return static_category; } \ virtual char const* what() const { return #name; } + // The ``torrent_added_alert`` is posted once every time a torrent is successfully + // added. It doesn't contain any members of its own, but inherits the torrent handle + // from its base class. + // It's posted when the ``status_notification`` bit is set in the alert_mask. struct TORRENT_EXPORT torrent_added_alert: torrent_alert { torrent_added_alert(torrent_handle const& h) @@ -122,6 +128,18 @@ namespace libtorrent virtual std::string message() const; }; + // The ``torrent_removed_alert`` is posted whenever a torrent is removed. Since + // the torrent handle in its baseclass will always be invalid (since the torrent + // is already removed) it has the info hash as a member, to identify it. + // It's posted when the ``status_notification`` bit is set in the alert_mask. + // + // Even though the ``handle`` member doesn't point to an existing torrent anymore, + // it is still useful for comparing to other handles, which may also no + // longer point to existing torrents, but to the same non-existing torrents. + // + // The ``torrent_handle`` acts as a ``weak_ptr``, even though its object no + // longer exists, it can still compare equal to another weak pointer which + // points to the same non-existent object. struct TORRENT_EXPORT torrent_removed_alert: torrent_alert { torrent_removed_alert(torrent_handle const& h, sha1_hash const& ih) @@ -135,7 +153,15 @@ namespace libtorrent sha1_hash info_hash; }; - struct TORRENT_EXPORT read_piece_alert: torrent_alert + // This alert is posted when the asynchronous read operation initiated by + // a call to torrent_handle::read_piece() is completed. If the read failed, the torrent + // is paused and an error state is set and the buffer member of the alert + // is 0. If successful, ``buffer`` points to a buffer containing all the data + // of the piece. ``piece`` is the piece index that was read. ``size`` is the + // number of bytes that was read. + // + // If the operation fails, ec will indicat what went wrong. + struct TORRENT_EXPORT read_piece_alert: torrent_alert { read_piece_alert(torrent_handle const& h , int p, boost::shared_array d, int s) @@ -164,12 +190,14 @@ namespace libtorrent int size; }; + // This is posted whenever an individual file completes its download. i.e. + // All pieces overlapping this file have passed their hash check. struct TORRENT_EXPORT file_completed_alert: torrent_alert { file_completed_alert(torrent_handle const& h - , int index_) + , int idx) : torrent_alert(h) - , index(index_) + , index(idx) {} TORRENT_DEFINE_ALERT(file_completed_alert); @@ -177,17 +205,20 @@ namespace libtorrent const static int static_category = alert::progress_notification; virtual std::string message() const; + // refers to the index of the file that completed. int index; }; + // This is posted as a response to a torrent_handle::rename_file() call, if the rename + // operation succeeds. struct TORRENT_EXPORT file_renamed_alert: torrent_alert { file_renamed_alert(torrent_handle const& h - , std::string const& name_ - , int index_) + , std::string const& n + , int idx) : torrent_alert(h) - , name(name_) - , index(index_) + , name(n) + , index(idx) {} TORRENT_DEFINE_ALERT(file_renamed_alert); @@ -197,17 +228,22 @@ namespace libtorrent virtual bool discardable() const { return false; } std::string name; + + // refers to the index of the file that was renamed, + // ``name`` is the new name of the file. int index; }; + // This is posted as a response to a torrent_handle::rename_file() call, if the rename + // operation failed. struct TORRENT_EXPORT file_rename_failed_alert: torrent_alert { file_rename_failed_alert(torrent_handle const& h - , int index_ - , error_code ec_) + , int idx + , error_code ec) : torrent_alert(h) - , index(index_) - , error(ec_) + , index(idx) + , error(ec) {} TORRENT_DEFINE_ALERT(file_rename_failed_alert); @@ -217,31 +253,93 @@ namespace libtorrent virtual std::string message() const; virtual bool discardable() const { return false; } + // refers to the index of the file that was supposed to be renamed, + // ``error`` is the error code returned from the filesystem. int index; error_code error; }; + // This alert is generated when a limit is reached that might have a negative impact on + // upload or download rate performance. struct TORRENT_EXPORT performance_alert: torrent_alert { enum performance_warning_t { + + // This warning means that the number of bytes queued to be written to disk + // exceeds the max disk byte queue setting (``session_settings::max_queued_disk_bytes``). + // This might restrict the download rate, by not queuing up enough write jobs + // to the disk I/O thread. When this alert is posted, peer connections are + // temporarily stopped from downloading, until the queued disk bytes have fallen + // below the limit again. Unless your ``max_queued_disk_bytes`` setting is already + // high, you might want to increase it to get better performance. outstanding_disk_buffer_limit_reached, - outstanding_request_limit_reached, + + // This is posted when libtorrent would like to send more requests to a peer, + // but it's limited by ``session_settings::max_out_request_queue``. The queue length + // libtorrent is trying to achieve is determined by the download rate and the + // assumed round-trip-time (``session_settings::request_queue_time``). The assumed + // rount-trip-time is not limited to just the network RTT, but also the remote disk + // access time and message handling time. It defaults to 3 seconds. The target number + // of outstanding requests is set to fill the bandwidth-delay product (assumed RTT + // times download rate divided by number of bytes per request). When this alert + // is posted, there is a risk that the number of outstanding requests is too low + // and limits the download rate. You might want to increase the ``max_out_request_queue`` + // setting. + outstanding_request_limit_reached, + + // This warning is posted when the amount of TCP/IP overhead is greater than the + // upload rate limit. When this happens, the TCP/IP overhead is caused by a much + // faster download rate, triggering TCP ACK packets. These packets eat into the + // rate limit specified to libtorrent. When the overhead traffic is greater than + // the rate limit, libtorrent will not be able to send any actual payload, such + // as piece requests. This means the download rate will suffer, and new requests + // can be sent again. There will be an equilibrium where the download rate, on + // average, is about 20 times the upload rate limit. If you want to maximize the + // download rate, increase the upload rate limit above 5% of your download capacity. upload_limit_too_low, + + // This is the same warning as ``upload_limit_too_low`` but referring to the download + // limit instead of upload. This suggests that your download rate limit is mcuh lower + // than your upload capacity. Your upload rate will suffer. To maximize upload rate, + // make sure your download rate limit is above 5% of your upload capacity. download_limit_too_low, + + // We're stalled on the disk. We want to write to the socket, and we can write + // but our send buffer is empty, waiting to be refilled from the disk. + // This either means the disk is slower than the network connection + // or that our send buffer watermark is too small, because we can + // send it all before the disk gets back to us. + // The number of bytes that we keep outstanding, requested from the disk, is calculated + // as follows:: + // + // min(512, max(upload_rate * send_buffer_watermark_factor / 100, send_buffer_watermark)) + // + // If you receive this alert, you migth want to either increase your ``send_buffer_watermark`` + // or ``send_buffer_watermark_factor``. send_buffer_watermark_too_low, + + // If the half (or more) of all upload slots are set as optimistic unchoke slots, this + // warning is issued. You probably want more regular (rate based) unchoke slots. too_many_optimistic_unchoke_slots, - bittyrant_with_no_uplimit, + + // If the disk write queue ever grows larger than half of the cache size, this warning + // is posted. The disk write queue eats into the total disk cache and leaves very little + // left for the actual cache. This causes the disk cache to oscillate in evicting large + // portions of the cache before allowing peers to download any more, onto the disk write + // queue. Either lower ``max_queued_disk_bytes`` or increase ``cache_size``. too_high_disk_queue_limit, + + bittyrant_with_no_uplimit, + + // This is generated if outgoing peer connections are failing because of *address in use* + // errors, indicating that ``session_settings::outgoing_ports`` is set and is too small of + // a range. Consider not using the ``outgoing_ports`` setting at all, or widen the range to + // include more ports. too_few_outgoing_ports, + too_few_file_descriptors, - - - - - - num_warnings }; @@ -260,14 +358,15 @@ namespace libtorrent performance_warning_t warning_code; }; + // Generated whenever a torrent changes its state. struct TORRENT_EXPORT state_changed_alert: torrent_alert { state_changed_alert(torrent_handle const& h - , torrent_status::state_t state_ - , torrent_status::state_t prev_state_) + , torrent_status::state_t st + , torrent_status::state_t prev_st) : torrent_alert(h) - , state(state_) - , prev_state(prev_state_) + , state(st) + , prev_state(prev_st) {} TORRENT_DEFINE_ALERT(state_changed_alert); @@ -276,19 +375,30 @@ namespace libtorrent virtual std::string message() const; + // the new state of the torrent. torrent_status::state_t state; + + // the previous state. torrent_status::state_t prev_state; }; + // This alert is generated on tracker time outs, premature disconnects, invalid response or + // a HTTP response other than "200 OK". From the alert you can get the handle to the torrent + // the tracker belongs to. + // + // The ``times_in_row`` member says how many times in a row this tracker has failed. + // ``status_code`` is the code returned from the HTTP server. 401 means the tracker needs + // authentication, 404 means not found etc. If the tracker timed out, the code will be set + // to 0. struct TORRENT_EXPORT tracker_error_alert: tracker_alert { tracker_error_alert(torrent_handle const& h , int times , int status - , std::string const& url_ + , std::string const& u , error_code const& e , std::string const& m) - : tracker_alert(h, url_) + : tracker_alert(h, u) , times_in_row(times) , status_code(status) , error(e) @@ -308,13 +418,16 @@ namespace libtorrent std::string msg; }; + // This alert is triggered if the tracker reply contains a warning field. Usually this + // means that the tracker announce was successful, but the tracker has a message to + // the client. struct TORRENT_EXPORT tracker_warning_alert: tracker_alert { tracker_warning_alert(torrent_handle const& h - , std::string const& url_ - , std::string const& msg_) - : tracker_alert(h, url_) - , msg(msg_) + , std::string const& u + , std::string const& m) + : tracker_alert(h, u) + , msg(m) { TORRENT_ASSERT(!url.empty()); } TORRENT_DEFINE_ALERT(tracker_warning_alert); @@ -322,42 +435,49 @@ namespace libtorrent const static int static_category = alert::tracker_notification | alert::error_notification; virtual std::string message() const; + // contains the warning message from the tracker. std::string msg; }; + // This alert is generated when a scrape request succeeds. struct TORRENT_EXPORT scrape_reply_alert: tracker_alert { scrape_reply_alert(torrent_handle const& h - , int incomplete_ - , int complete_ - , std::string const& url_) - : tracker_alert(h, url_) - , incomplete(incomplete_) - , complete(complete_) + , int incomp + , int comp + , std::string const& u) + : tracker_alert(h, u) + , incomplete(incomp) + , complete(comp) { TORRENT_ASSERT(!url.empty()); } TORRENT_DEFINE_ALERT(scrape_reply_alert); virtual std::string message() const; + // the data returned in the scrape response. These numbers + // may be -1 if the reponse was malformed. int incomplete; int complete; }; + // If a scrape request fails, this alert is generated. This might be due + // to the tracker timing out, refusing connection or returning an http response + // code indicating an error. struct TORRENT_EXPORT scrape_failed_alert: tracker_alert { scrape_failed_alert(torrent_handle const& h - , std::string const& url_ + , std::string const& u , error_code const& e) - : tracker_alert(h, url_) + : tracker_alert(h, u) , msg(convert_from_native(e.message())) { TORRENT_ASSERT(!url.empty()); } scrape_failed_alert(torrent_handle const& h - , std::string const& url_ - , std::string const& msg_) - : tracker_alert(h, url_) - , msg(msg_) + , std::string const& u + , std::string const& m) + : tracker_alert(h, u) + , msg(m) { TORRENT_ASSERT(!url.empty()); } TORRENT_DEFINE_ALERT(scrape_failed_alert); @@ -365,15 +485,19 @@ namespace libtorrent const static int static_category = alert::tracker_notification | alert::error_notification; virtual std::string message() const; + // contains a message describing the error. std::string msg; }; + // This alert is only for informational purpose. It is generated when a tracker announce + // succeeds. It is generated regardless what kind of tracker was used, be it UDP, HTTP or + // the DHT. struct TORRENT_EXPORT tracker_reply_alert: tracker_alert { tracker_reply_alert(torrent_handle const& h , int np - , std::string const& url_) - : tracker_alert(h, url_) + , std::string const& u) + : tracker_alert(h, u) , num_peers(np) { TORRENT_ASSERT(!url.empty()); } @@ -381,9 +505,16 @@ namespace libtorrent virtual std::string message() const; + // tells how many peers the tracker returned in this response. This is + // not expected to be more thant the ``num_want`` settings. These are not necessarily + // all new peers, some of them may already be connected. int num_peers; }; + // This alert is generated each time the DHT receives peers from a node. ``num_peers`` + // is the number of peers we received in this packet. Typically these packets are + // received from multiple DHT nodes, and so the alerts are typically generated + // a few at a time. struct TORRENT_EXPORT dht_reply_alert: tracker_alert { dht_reply_alert(torrent_handle const& h @@ -399,21 +530,32 @@ namespace libtorrent int num_peers; }; + // This alert is generated each time a tracker announce is sent (or attempted to be sent). + // There are no extra data members in this alert. The url can be found in the base class + // however. struct TORRENT_EXPORT tracker_announce_alert: tracker_alert { tracker_announce_alert(torrent_handle const& h - , std::string const& url_, int event_) - : tracker_alert(h, url_) - , event(event_) + , std::string const& u, int e) + : tracker_alert(h, u) + , event(e) { TORRENT_ASSERT(!url.empty()); } TORRENT_DEFINE_ALERT(tracker_announce_alert); virtual std::string message() const; + // specifies what event was sent to the tracker. It is defined as: + // + // 0. None + // 1. Completed + // 2. Started + // 3. Stopped int event; }; + // This alert is generated when a finished piece fails its hash check. You can get the handle + // to the torrent which got the failed piece and the index of the piece itself from the alert. struct TORRENT_EXPORT hash_failed_alert: torrent_alert { hash_failed_alert( @@ -431,6 +573,8 @@ namespace libtorrent int piece_index; }; + // This alert is generated when a peer is banned because it has sent too many corrupt pieces + // to us. ``ip`` is the endpoint to the peer that was banned. struct TORRENT_EXPORT peer_ban_alert: peer_alert { peer_ban_alert(torrent_handle h, tcp::endpoint const& ep @@ -443,6 +587,8 @@ namespace libtorrent virtual std::string message() const; }; + // This alert is generated when a peer is unsnubbed. Essentially when it was snubbed for stalling + // sending data, and now it started sending data again. struct TORRENT_EXPORT peer_unsnubbed_alert: peer_alert { peer_unsnubbed_alert(torrent_handle h, tcp::endpoint const& ep @@ -455,6 +601,8 @@ namespace libtorrent virtual std::string message() const; }; + // This alert is generated when a peer is snubbed, when it stops sending data when we request + // it. struct TORRENT_EXPORT peer_snubbed_alert: peer_alert { peer_snubbed_alert(torrent_handle h, tcp::endpoint const& ep @@ -467,6 +615,8 @@ namespace libtorrent virtual std::string message() const; }; + // This alert is generated when a peer sends invalid data over the peer-peer protocol. The peer + // will be disconnected, but you get its ip address from the alert, to identify it. struct TORRENT_EXPORT peer_error_alert: peer_alert { peer_error_alert(torrent_handle const& h, tcp::endpoint const& ep @@ -487,6 +637,7 @@ namespace libtorrent return peer_alert::message() + " peer error: " + convert_from_native(error.message()); } + // tells you what error caused this alert. error_code error; #ifndef TORRENT_NO_DEPRECATE @@ -494,6 +645,7 @@ namespace libtorrent #endif }; + // This alert is posted every time an outgoing peer connect attempts succeeds. struct TORRENT_EXPORT peer_connect_alert: peer_alert { peer_connect_alert(torrent_handle h, tcp::endpoint const& ep @@ -510,6 +662,8 @@ namespace libtorrent int socket_type; }; + // This alert is generated when a peer is disconnected for any reason (other than the ones + // covered by peer_error_alert ). struct TORRENT_EXPORT peer_disconnected_alert: peer_alert { peer_disconnected_alert(torrent_handle const& h, tcp::endpoint const& ep @@ -527,6 +681,7 @@ namespace libtorrent const static int static_category = alert::debug_notification; virtual std::string message() const; + // tells you what error caused peer to disconnect. error_code error; #ifndef TORRENT_NO_DEPRECATE @@ -534,6 +689,9 @@ namespace libtorrent #endif }; + // This is a debug alert that is generated by an incoming invalid piece request. + // ``ip`` is the address of the peer and the ``request`` is the actual incoming + // request from the peer. See peer_request for more info. struct TORRENT_EXPORT invalid_request_alert: peer_alert { invalid_request_alert(torrent_handle const& h, tcp::endpoint const& ep @@ -549,6 +707,9 @@ namespace libtorrent peer_request request; }; + // This alert is generated when a torrent switches from being a downloader to a seed. + // It will only be generated once per torrent. It contains a torrent_handle to the + // torrent in question. struct TORRENT_EXPORT torrent_finished_alert: torrent_alert { torrent_finished_alert( @@ -580,6 +741,7 @@ namespace libtorrent int piece_index; }; + // This alert is generated when a peer rejects or ignores a piece request. struct TORRENT_EXPORT request_dropped_alert: peer_alert { request_dropped_alert(const torrent_handle& h, tcp::endpoint const& ep @@ -599,6 +761,7 @@ namespace libtorrent int piece_index; }; + // This alert is generated when a block request times out. struct TORRENT_EXPORT block_timeout_alert: peer_alert { block_timeout_alert(const torrent_handle& h, tcp::endpoint const& ep @@ -618,6 +781,7 @@ namespace libtorrent int piece_index; }; + // This alert is generated when a block request receives a response. struct TORRENT_EXPORT block_finished_alert: peer_alert { block_finished_alert(const torrent_handle& h, tcp::endpoint const& ep @@ -636,6 +800,7 @@ namespace libtorrent int piece_index; }; + // This alert is generated when a block request is sent to a peer. struct TORRENT_EXPORT block_downloading_alert: peer_alert { block_downloading_alert(const torrent_handle& h, tcp::endpoint const& ep @@ -656,6 +821,8 @@ namespace libtorrent int piece_index; }; + // This alert is generated when a block is received that was not requested or + // whose request timed out. struct TORRENT_EXPORT unwanted_block_alert: peer_alert { unwanted_block_alert(const torrent_handle& h, tcp::endpoint const& ep @@ -673,11 +840,15 @@ namespace libtorrent int piece_index; }; + // The ``storage_moved_alert`` is generated when all the disk IO has completed and the + // files have been moved, as an effect of a call to ``torrent_handle::move_storage``. This + // is useful to synchronize with the actual disk. The ``path`` member is the new path of + // the storage. struct TORRENT_EXPORT storage_moved_alert: torrent_alert { - storage_moved_alert(torrent_handle const& h, std::string const& path_) + storage_moved_alert(torrent_handle const& h, std::string const& p) : torrent_alert(h) - , path(path_) + , path(p) {} TORRENT_DEFINE_ALERT(storage_moved_alert); @@ -692,11 +863,13 @@ namespace libtorrent std::string path; }; + // The ``storage_moved_failed_alert`` is generated when an attempt to move the storage, + // via torrent_handle::move_storage(), fails. struct TORRENT_EXPORT storage_moved_failed_alert: torrent_alert { - storage_moved_failed_alert(torrent_handle const& h, error_code const& ec_) + storage_moved_failed_alert(torrent_handle const& h, error_code const& e) : torrent_alert(h) - , error(ec_) + , error(e) {} TORRENT_DEFINE_ALERT(storage_moved_failed_alert); @@ -711,6 +884,15 @@ namespace libtorrent error_code error; }; + // This alert is generated when a request to delete the files of a torrent complete. + // + // The ``info_hash`` is the info-hash of the torrent that was just deleted. Most of + // the time the torrent_handle in the ``torrent_alert`` will be invalid by the time + // this alert arrives, since the torrent is being deleted. The ``info_hash`` member + // is hence the main way of identifying which torrent just completed the delete. + // + // This alert is posted in the ``storage_notification`` category, and that bit + // needs to be set in the alert_mask. struct TORRENT_EXPORT torrent_deleted_alert: torrent_alert { torrent_deleted_alert(torrent_handle const& h, sha1_hash const& ih) @@ -727,6 +909,7 @@ namespace libtorrent sha1_hash info_hash; }; + // This alert is generated when a request to delete the files of a torrent fails. struct TORRENT_EXPORT torrent_delete_failed_alert: torrent_alert { torrent_delete_failed_alert(torrent_handle const& h, error_code const& e) @@ -749,6 +932,7 @@ namespace libtorrent } virtual bool discardable() const { return false; } + // tells you why it failed. error_code error; #ifndef TORRENT_NO_DEPRECATE @@ -756,6 +940,9 @@ namespace libtorrent #endif }; + // This alert is generated as a response to a ``torrent_handle::save_resume_data`` request. + // It is generated once the disk IO thread is done writing the state for this torrent. + struct TORRENT_EXPORT save_resume_data_alert: torrent_alert { save_resume_data_alert(boost::shared_ptr const& rd @@ -771,9 +958,12 @@ namespace libtorrent { return torrent_alert::message() + " resume data generated"; } virtual bool discardable() const { return false; } + // points to the resume data. boost::shared_ptr resume_data; }; + // This alert is generated instead of ``save_resume_data_alert`` if there was an error + // generating the resume data. ``error`` describes what went wrong. struct TORRENT_EXPORT save_resume_data_failed_alert: torrent_alert { save_resume_data_failed_alert(torrent_handle const& h @@ -804,6 +994,9 @@ namespace libtorrent #endif }; + // This alert is generated as a response to a ``torrent_handle::pause`` request. It is + // generated once all disk IO is complete and the files in the torrent have been closed. + // This is useful for synchronizing with the disk. struct TORRENT_EXPORT torrent_paused_alert: torrent_alert { torrent_paused_alert(torrent_handle const& h) @@ -817,6 +1010,8 @@ namespace libtorrent { return torrent_alert::message() + " paused"; } }; + // This alert is generated as a response to a torrent_handle::resume() request. It is + // generated when a torrent goes from a paused state to an active state. struct TORRENT_EXPORT torrent_resumed_alert: torrent_alert { torrent_resumed_alert(torrent_handle const& h) @@ -842,24 +1037,25 @@ namespace libtorrent { return torrent_alert::message() + " checked"; } }; + // This alert is generated when a HTTP seed name lookup fails. struct TORRENT_EXPORT url_seed_alert: torrent_alert { url_seed_alert( torrent_handle const& h - , std::string const& url_ + , std::string const& u , error_code const& e) : torrent_alert(h) - , url(url_) + , url(u) , msg(convert_from_native(e.message())) {} url_seed_alert( torrent_handle const& h - , std::string const& url_ - , std::string const& msg_) + , std::string const& u + , std::string const& m) : torrent_alert(h) - , url(url_) - , msg(msg_) + , url(u) + , msg(m) {} TORRENT_DEFINE_ALERT(url_seed_alert); @@ -871,10 +1067,15 @@ namespace libtorrent + url + ") failed: " + msg; } + // the HTTP seed that failed std::string url; + + // the error message, potentially from the server std::string msg; }; + // If the storage fails to read or write files that it needs access to, this alert is + // generated and the torrent is paused. struct TORRENT_EXPORT file_error_alert: torrent_alert { file_error_alert( @@ -900,8 +1101,11 @@ namespace libtorrent return torrent_alert::message() + " file (" + file + ") error: " + convert_from_native(error.message()); } - + + // the path to the file that was accessed when the error occurred. std::string file; + + // the error code describing the error. error_code error; #ifndef TORRENT_NO_DEPRECATE @@ -909,6 +1113,10 @@ namespace libtorrent #endif }; + // This alert is generated when the metadata has been completely received and the info-hash + // failed to match it. i.e. the metadata that was received was corrupt. libtorrent will + // automatically retry to fetch it in this case. This is only relevant when running a + // torrent-less download, with the metadata extension provided by libtorrent. struct TORRENT_EXPORT metadata_failed_alert: torrent_alert { metadata_failed_alert(const torrent_handle& h) @@ -922,6 +1130,30 @@ namespace libtorrent { return torrent_alert::message() + " invalid metadata received"; } }; + // This alert is generated when the metadata has been completely received and the torrent + // can start downloading. It is not generated on torrents that are started with metadata, but + // only those that needs to download it from peers (when utilizing the libtorrent extension). + // + // There are no additional data members in this alert. + // + // Typically, when receiving this alert, you would want to save the torrent file in order + // to load it back up again when the session is restarted. Here's an example snippet of + // code to do that:: + // + // torrent_handle h = alert->handle(); + // if (h.is_valid()) { + // boost::intrusive_ptr ti = h.torrent_file(); + // create_torrent ct(*ti); + // entry te = ct.generate(); + // std::vector buffer; + // bencode(std::back_inserter(buffer), te); + // FILE* f = fopen((to_hex(ti->info_hash().to_string()) + ".torrent").c_str(), "wb+"); + // if (f) { + // fwrite(&buffer[0], 1, buffer.size(), f); + // fclose(f); + // } + // } + // struct TORRENT_EXPORT metadata_received_alert: torrent_alert { metadata_received_alert( @@ -958,6 +1190,10 @@ namespace libtorrent error_code error; }; + // Whenever libtorrent learns about the machines external IP, this alert is + // generated. The external IP address can be acquired from the tracker (if it + // supports that) or from peers that supports the extension protocol. + // The address can be accessed through the ``external_address`` member. struct TORRENT_EXPORT external_ip_alert: alert { external_ip_alert(address const& ip) @@ -976,6 +1212,15 @@ namespace libtorrent address external_address; }; + // This alert is generated when none of the ports, given in the port range, to + // session can be opened for listening. The ``endpoint`` member is the + // interface and port that failed, ``error`` is the error code describing + // the failure. + // + // libtorrent may sometimes try to listen on port 0, if all other ports failed. + // Port 0 asks the operating system to pick a port that's free). If that fails + // you may see a listen_failed_alert with port 0 even if you didn't ask to + // listen on it. struct TORRENT_EXPORT listen_failed_alert: alert { listen_failed_alert( @@ -1002,6 +1247,9 @@ namespace libtorrent int operation; }; + // This alert is posted when the listen port succeeds to be opened on a + // particular interface. ``endpoint`` is the endpoint that successfully + // was opened for listening. struct TORRENT_EXPORT listen_succeeded_alert: alert { listen_succeeded_alert(tcp::endpoint const& ep) @@ -1017,6 +1265,12 @@ namespace libtorrent tcp::endpoint endpoint; }; + // This alert is generated when a NAT router was successfully found but some + // part of the port mapping request failed. It contains a text message that + // may help the user figure out what is wrong. This alert is not generated in + // case it appears the client is not running on a NAT:ed network or if it + // appears there is no NAT router that can be remote controlled to add port + // mappings. struct TORRENT_EXPORT portmap_error_alert: alert { portmap_error_alert(int i, int t, error_code const& e) @@ -1033,14 +1287,24 @@ namespace libtorrent | alert::error_notification; virtual std::string message() const; + // refers to the mapping index of the port map that failed, i.e. + // the index returned from add_mapping(). int mapping; + + // is 0 for NAT-PMP and 1 for UPnP. int map_type; + + // tells you what failed. error_code error; #ifndef TORRENT_NO_DEPRECATE std::string msg; #endif }; + // This alert is generated when a NAT router was successfully found and + // a port was successfully mapped on it. On a NAT:ed network with a NAT-PMP + // capable router, this is typically generated once when mapping the TCP + // port and, if DHT is enabled, when the UDP port is mapped. struct TORRENT_EXPORT portmap_alert: alert { portmap_alert(int i, int port, int t) @@ -1052,11 +1316,21 @@ namespace libtorrent const static int static_category = alert::port_mapping_notification; virtual std::string message() const; + // refers to the mapping index of the port map that failed, i.e. + // the index returned from add_mapping(). int mapping; + + // the external port allocated for the mapping. int external_port; + + // 0 for NAT-PMP and 1 for UPnP. int map_type; }; + // This alert is generated to log informational events related to either + // UPnP or NAT-PMP. They contain a log line and the type (0 = NAT-PMP + // and 1 = UPnP). Displaying these messages to an end user is only useful + // for debugging the UPnP or NAT-PMP implementation. struct TORRENT_EXPORT portmap_log_alert: alert { portmap_log_alert(int t, std::string const& m) @@ -1072,6 +1346,9 @@ namespace libtorrent std::string msg; }; + // This alert is generated when a fastresume file has been passed to add_torrent() but the + // files on disk did not match the fastresume file. The error_code explains the reason why the + // resume file was rejected. struct TORRENT_EXPORT fastresume_rejected_alert: torrent_alert { fastresume_rejected_alert(torrent_handle const& h @@ -1098,11 +1375,19 @@ namespace libtorrent #endif }; + // This alert is posted when an incoming peer connection, or a peer that's about to be added + // to our peer list, is blocked for some reason. This could be any of: + // + // * the IP filter + // * i2p mixed mode restrictions (a normal peer is not allowed on an i2p swarm) + // * the port filter + // * the peer has a low port and ``no_connect_privileged_ports`` is enabled + // * the protocol of the peer is blocked (uTP/TCP blocking) struct TORRENT_EXPORT peer_blocked_alert: torrent_alert { - peer_blocked_alert(torrent_handle const& h, address const& ip_) + peer_blocked_alert(torrent_handle const& h, address const& i) : torrent_alert(h) - , ip(ip_) + , ip(i) {} TORRENT_DEFINE_ALERT(peer_blocked_alert); @@ -1114,16 +1399,19 @@ namespace libtorrent return torrent_alert::message() + ": blocked peer: " + ip.to_string(ec); } + // the address that was blocked. address ip; }; + // This alert is generated when a DHT node announces to an info-hash on our DHT node. It belongs + // to the ``dht_notification`` category. struct TORRENT_EXPORT dht_announce_alert: alert { - dht_announce_alert(address const& ip_, int port_ - , sha1_hash const& info_hash_) - : ip(ip_) - , port(port_) - , info_hash(info_hash_) + dht_announce_alert(address const& i, int p + , sha1_hash const& ih) + : ip(i) + , port(p) + , info_hash(ih) {} TORRENT_DEFINE_ALERT(dht_announce_alert); @@ -1136,10 +1424,12 @@ namespace libtorrent sha1_hash info_hash; }; + // This alert is generated when a DHT node sends a ``get_peers`` message to our DHT node. + // It belongs to the ``dht_notification`` category. struct TORRENT_EXPORT dht_get_peers_alert: alert { - dht_get_peers_alert(sha1_hash const& info_hash_) - : info_hash(info_hash_) + dht_get_peers_alert(sha1_hash const& ih) + : info_hash(ih) {} TORRENT_DEFINE_ALERT(dht_get_peers_alert); @@ -1150,6 +1440,9 @@ namespace libtorrent sha1_hash info_hash; }; + // This alert is posted approximately once every second, and it contains + // byte counters of most statistics that's tracked for torrents. Each active + // torrent posts these alerts regularly. struct TORRENT_EXPORT stats_alert: torrent_alert { stats_alert(torrent_handle const& h, int interval @@ -1177,10 +1470,21 @@ namespace libtorrent num_channels }; + // an array of samples. The enum describes what each + // sample is a measurement of. All of these are raw, and not smoothing is performed. int transferred[num_channels]; + + // the number of milliseconds during which these stats + // were collected. This is typically just above 1000, but if CPU is + // limited, it may be higher than that. int interval; }; + // This alert is posted when the disk cache has been flushed for a specific torrent + // as a result of a call to torrent_handle::flush_cache(). This alert belongs to the + // ``storage_notification`` category, which must be enabled to let this alert through. + // The alert is also posted when removing a torrent from the session, once the outstanding + // cache flush is complete and the torrent does no longer have any files open. struct TORRENT_EXPORT cache_flushed_alert: torrent_alert { cache_flushed_alert(torrent_handle const& h); @@ -1190,13 +1494,17 @@ namespace libtorrent const static int static_category = alert::storage_notification; }; + // This alert is posted when a bittorrent feature is blocked because of the + // anonymous mode. For instance, if the tracker proxy is not set up, no + // trackers will be used, because trackers can only be used through proxies + // when in anonymous mode. struct TORRENT_EXPORT anonymous_mode_alert: torrent_alert { anonymous_mode_alert(torrent_handle const& h - , int kind_, std::string const& str_) + , int k, std::string const& s) : torrent_alert(h) - , kind(kind_) - , str(str_) + , kind(k) + , str(s) {} TORRENT_DEFINE_ALERT(anonymous_mode_alert); @@ -1206,18 +1514,24 @@ namespace libtorrent enum kind_t { + // means that there's no proxy set up for tracker + // communication and the tracker will not be contacted. + // The tracker which this failed for is specified in the ``str`` member. tracker_not_anonymous = 0 }; + // specifies what error this is, see kind_t. int kind; std::string str; }; + // This alert is generated when we receive a local service discovery message from a peer + // for a torrent we're currently participating in. struct TORRENT_EXPORT lsd_peer_alert: peer_alert { lsd_peer_alert(torrent_handle const& h - , tcp::endpoint const& ip_) - : peer_alert(h, ip_, peer_id(0)) + , tcp::endpoint const& i) + : peer_alert(h, i, peer_id(0)) {} TORRENT_DEFINE_ALERT(lsd_peer_alert); @@ -1229,9 +1543,9 @@ namespace libtorrent struct TORRENT_EXPORT trackerid_alert: tracker_alert { trackerid_alert(torrent_handle const& h - , std::string const& url_ + , std::string const& u , const std::string& id) - : tracker_alert(h, url_) + : tracker_alert(h, u) , trackerid(id) {} @@ -1243,6 +1557,7 @@ namespace libtorrent std::string trackerid; }; + // This alert is posted when the initial DHT bootstrap is done. struct TORRENT_EXPORT dht_bootstrap_alert: alert { dht_bootstrap_alert() {} @@ -1253,10 +1568,15 @@ namespace libtorrent virtual std::string message() const; }; + // This alert is posted on RSS feed events such as start of RSS feed updates, + // successful completed updates and errors during updates. + // + // This alert is only posted if the ``rss_notifications`` category is enabled + // in the alert_mask. struct TORRENT_EXPORT rss_alert: alert { - rss_alert(feed_handle h, std::string const& url_, int state_, error_code const& ec) - : handle(h), url(url_), state(state_), error(ec) + rss_alert(feed_handle h, std::string const& u, int s, error_code const& ec) + : handle(h), url(u), state(s), error(ec) {} TORRENT_DEFINE_ALERT(rss_alert); @@ -1266,15 +1586,35 @@ namespace libtorrent enum state_t { - state_updating, state_updated, state_error + // An update of this feed was just initiated, it will either succeed + // or fail soon. + state_updating, + + // The feed just completed a successful update, there may be new items + // in it. If you're adding torrents manually, you may want to request + // the feed status of the feed and look through the ``items`` vector. + state_updated, + + // An error just occurred. See the ``error`` field for information on + // what went wrong. + state_error }; + // the handle to the feed which generated this alert. feed_handle handle; + + // a short cut to access the url of the feed, without + // having to call feed_handle::get_settings(). std::string url; + + // one of the values from rss_alert::state_t. int state; + + // an error code used for when an error occurs on the feed. error_code error; }; + // This is posted whenever a torrent is transitioned into the error state. struct TORRENT_EXPORT torrent_error_alert: torrent_alert { torrent_error_alert(torrent_handle const& h @@ -1288,9 +1628,14 @@ namespace libtorrent const static int static_category = alert::error_notification | alert::status_notification; virtual std::string message() const; + // specifies which error the torrent encountered. error_code error; }; + // This is always posted for SSL torrents. This is a reminder to the client that + // the torrent won't work unless torrent_handle::set_ssl_certificate() is called with + // a valid certificate. Valid certificates MUST be signed by the SSL certificate + // in the .torrent file. struct TORRENT_EXPORT torrent_need_cert_alert: torrent_alert { torrent_need_cert_alert(torrent_handle const& h) @@ -1306,11 +1651,17 @@ namespace libtorrent error_code error; }; + // The incoming connection alert is posted every time we successfully accept + // an incoming connection, through any mean. The most straigh-forward ways + // of accepting incoming connections are through the TCP listen socket and + // the UDP listen socket for uTP sockets. However, connections may also be + // accepted ofer a Socks5 or i2p listen socket, or via a torrent specific + // listen socket for SSL torrents. struct TORRENT_EXPORT incoming_connection_alert: alert { - incoming_connection_alert(int type_, tcp::endpoint const& ip_) - : socket_type(type_) - , ip(ip_) + incoming_connection_alert(int t, tcp::endpoint const& i) + : socket_type(t) + , ip(i) {} TORRENT_DEFINE_ALERT(incoming_connection_alert); @@ -1318,10 +1669,30 @@ namespace libtorrent const static int static_category = alert::peer_notification; virtual std::string message() const; + // tells you what kind of socket the connection was accepted + // as: + // + // 0. none (no socket instantiated) + // 1. TCP + // 2. Socks5 + // 3. HTTP + // 4. uTP + // 5. i2p + // 6. SSL/TCP + // 7. SSL/Socks5 + // 8. HTTPS (SSL/HTTP) + // 9. SSL/uTP + // int socket_type; + + // is the IP address and port the connection came from. tcp::endpoint ip; }; + // This alert is always posted when a torrent was attempted to be added + // and contains the return status of the add operation. The torrent handle of the new + // torrent can be found in the base class' ``handle`` member. If adding + // the torrent failed, ``error`` contains the error code. struct TORRENT_EXPORT add_torrent_alert : torrent_alert { add_torrent_alert(torrent_handle h, add_torrent_params const& p, error_code ec) @@ -1336,10 +1707,18 @@ namespace libtorrent virtual std::string message() const; virtual bool discardable() const { return false; } + // a copy of the parameters used when adding the torrent, it can be used + // to identify which invocation to ``async_add_torrent()`` caused this alert. add_torrent_params params; + + // set to the error, if one occurred while adding the torrent. error_code error; }; + // This alert is only posted when requested by the user, by calling session::post_torrent_updates() + // on the session. It contains the torrent status of all torrents that changed + // since last time this message was posted. Its category is ``status_notification``, but + // it's not subject to filtering, since it's only manually posted anyway. struct TORRENT_EXPORT state_update_alert : alert { TORRENT_DEFINE_ALERT(state_update_alert); @@ -1348,9 +1727,19 @@ namespace libtorrent virtual std::string message() const; virtual bool discardable() const { return false; } + // contains the torrent status of all torrents that changed since last time + // this message was posted. Note that you can map a torrent status to a specific torrent + // via its ``handle`` member. The receiving end is suggested to have all torrents sorted + // by the torrent_handle or hashed by it, for efficient updates. std::vector status; }; + // When a torrent changes its info-hash, this alert is posted. This only happens in very + // specific cases. For instance, when a torrent is downloaded from a URL, the true info + // hash is not known immediately. First the .torrent file must be downloaded and parsed. + // + // Once this download completes, the ``torrent_update_alert`` is posted to notify the client + // of the info-hash changing. struct TORRENT_EXPORT torrent_update_alert : torrent_alert { torrent_update_alert(torrent_handle h, sha1_hash const& old_hash, sha1_hash const& new_hash) @@ -1365,10 +1754,16 @@ namespace libtorrent virtual std::string message() const; virtual bool discardable() const { return false; } + // ``old_ih`` and ``new_ih`` are the previous and new info-hash for the torrent, respectively. sha1_hash old_ih; sha1_hash new_ih; }; + // This alert is posted every time a new RSS item (i.e. torrent) is received + // from an RSS feed. + // + // It is only posted if the ``rss_notifications`` category is enabled in the + // alert_mask. struct TORRENT_EXPORT rss_item_alert : alert { rss_item_alert(feed_handle h, feed_item const& item) diff --git a/include/libtorrent/peer_request.hpp b/include/libtorrent/peer_request.hpp index bc34ec6eb..5ac535957 100644 --- a/include/libtorrent/peer_request.hpp +++ b/include/libtorrent/peer_request.hpp @@ -35,7 +35,7 @@ POSSIBILITY OF SUCH DAMAGE. namespace libtorrent { - struct TORRENT_EXTRA_EXPORT peer_request + struct TORRENT_EXPORT peer_request { // the index of the piece in which the range starts. int piece; diff --git a/include/libtorrent/ptime.hpp b/include/libtorrent/ptime.hpp index cbbe1dcf3..fcca0c0ec 100644 --- a/include/libtorrent/ptime.hpp +++ b/include/libtorrent/ptime.hpp @@ -84,30 +84,43 @@ namespace libtorrent inline bool is_negative(time_duration dt) { return dt.diff < 0; } + // 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)); } diff --git a/include/libtorrent/session.hpp b/include/libtorrent/session.hpp index a477ce30e..12384e0c5 100644 --- a/include/libtorrent/session.hpp +++ b/include/libtorrent/session.hpp @@ -658,7 +658,6 @@ namespace libtorrent enum options_t { - none = 0, delete_files = 1 }; @@ -675,7 +674,7 @@ namespace libtorrent // no guarantee that adding the same torrent immediately after it was removed will not throw // a libtorrent_exception exception. Once the torrent is deleted, a torrent_deleted_alert // is posted. - void remove_torrent(const torrent_handle& h, int options = none); + void remove_torrent(const torrent_handle& h, int options = 0); // Sets the session settings and the packet encryption settings respectively. // See session_settings and pe_settings for more information on available diff --git a/include/libtorrent/torrent_handle.hpp b/include/libtorrent/torrent_handle.hpp index 8ed1627f6..faabc2281 100644 --- a/include/libtorrent/torrent_handle.hpp +++ b/include/libtorrent/torrent_handle.hpp @@ -244,7 +244,7 @@ namespace libtorrent // calling this function. // // When the read operation is completed, it is passed back through an alert, - // read_piece_alert_. Since this alert is a reponse to an explicit call, it will + // read_piece_alert. Since this alert is a reponse to an explicit call, it will // always be posted, regardless of the alert mask. // // Note that if you read multiple pieces, the read operations are not guaranteed to @@ -258,7 +258,7 @@ namespace libtorrent // takes a reference to a vector that will be cleared and filled // with one entry for each peer connected to this torrent, given the handle is valid. If the - // torrent_handle_ is invalid, it will throw libtorrent_exception exception. Each entry in + // torrent_handle is invalid, it will throw libtorrent_exception exception. Each entry in // the vector contains information about that particular peer. See peer_info. void get_peer_info(std::vector& v) const; @@ -285,8 +285,8 @@ namespace libtorrent }; // ``status()`` will return a structure with information about the status of this - // torrent. If the torrent_handle_ is invalid, it will throw libtorrent_exception_ exception. - // See torrent_status_. The ``flags`` argument filters what information is returned + // torrent. If the torrent_handle is invalid, it will throw libtorrent_exception exception. + // See torrent_status. The ``flags`` argument filters what information is returned // in the torrent_status. Some information in there is relatively expensive to calculate, and // if you're not interested in it (and see performance issues), you can filter them out. // @@ -311,7 +311,7 @@ namespace libtorrent // // The ``flags`` parameter can be used to ask libtorrent to send an alert once the // piece has been downloaded, by passing alert_when_available. When set, the - // read_piece_alert_ alert will be delivered, with the piece data, when it's downloaded. + // read_piece_alert alert will be delivered, with the piece data, when it's downloaded. // // If the piece is already downloaded when this call is made, nothing happens, unless // the alert_when_available flag is set, in which case it will do the same thing @@ -359,7 +359,7 @@ namespace libtorrent // This function fills in the supplied vector with the the number of bytes downloaded // of each file in this torrent. The progress values are ordered the same as the files - // in the `torrent_info`_. This operation is not very cheap. Its complexity is *O(n + mj)*. + // in the torrent_info. This operation is not very cheap. Its complexity is *O(n + mj)*. // Where *n* is the number of files, *m* is the number of downloading pieces and *j* // is the number of blocks in a piece. // @@ -431,7 +431,7 @@ namespace libtorrent // or if the torrent it refers to has been aborted. Note that a handle may become invalid after // it has been added to the session. Usually this is because the storage for the torrent is // somehow invalid or if the filenames are not allowed (and hence cannot be opened/created) on - // your filesystem. If such an error occurs, a file_error_alert_ is generated and all handles + // your filesystem. If such an error occurs, a file_error_alert is generated and all handles // that refers to that torrent will become invalid. bool is_valid() const; @@ -441,7 +441,7 @@ namespace libtorrent // ``pause()``, and ``resume()`` will disconnect all peers and reconnect all peers respectively. // When a torrent is paused, it will however remember all share ratios to all peers and remember // all potential (not connected) peers. Torrents may be paused automatically if there is a file - // error (e.g. disk full) or something similar. See file_error_alert_. + // error (e.g. disk full) or something similar. See file_error_alert. // // To know if a torrent is paused or not, call ``torrent_handle::status()`` and inspect // ``torrent_status::paused``. @@ -477,7 +477,7 @@ namespace libtorrent // Instructs libtorrent to flush all the disk caches for this torrent and close all // file handles. This is done asynchronously and you will be notified that it's complete - // through cache_flushed_alert_. + // through cache_flushed_alert. // // Note that by the time you get the alert, libtorrent may have cached more data for the // torrent, but you are guaranteed that whatever cached data libtorrent had by the time @@ -497,7 +497,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_ + // ``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`` @@ -542,7 +542,7 @@ namespace libtorrent // In full allocation mode the reume data is never invalidated by subsequent // writes to the files, since pieces won't move around. This means that you don't need to // pause before writing resume data in full or sparse mode. If you don't, however, any data written to - // disk after you saved resume data and before the session_ closed is lost. + // disk after you saved resume data and before the session closed is lost. // // It also means that if the resume data is out dated, libtorrent will not re-check the files, but assume // that it is fairly recent. The assumption is that it's better to loose a little bit than to re-check @@ -647,8 +647,8 @@ namespace libtorrent void queue_position_bottom() const; // Sets or gets the flag that derermines if countries should be resolved for the peers of this - // torrent. It defaults to false. If it is set to true, the peer_info_ structure for the peers - // in this torrent will have their ``country`` member set. See peer_info_ for more information + // torrent. It defaults to false. If it is set to true, the peer_info structure for the peers + // in this torrent will have their ``country`` member set. See peer_info for more information // on how to interpret this field. void resolve_countries(bool r); bool resolve_countries() const; @@ -672,7 +672,7 @@ namespace libtorrent // to any peers until it has one. It's typically desirable to resume the torrent after setting the // ssl certificate. // - // If you receive a torrent_need_cert_alert_, you need to call this to provide a valid cert. If you + // If you receive a torrent_need_cert_alert, you need to call this to provide a valid cert. If you // don't have a cert you won't be allowed to connect to any peers. void set_ssl_certificate(std::string const& certificate , std::string const& private_key @@ -761,7 +761,7 @@ namespace libtorrent void filter_files(std::vector const& files) const TORRENT_DEPRECATED; // ``use_interface()`` sets the network interface this torrent will use when it opens outgoing - // connections. By default, it uses the same interface as the session_ uses to listen on. The + // connections. By default, it uses the same interface as the session uses to listen on. The // parameter must be a string containing one or more, comma separated, ip-address (either an // IPv4 or IPv6 address). When specifying multiple interfaces, the torrent will round-robin // which interface to use for each outgoing conneciton. This is useful for clients that are @@ -870,8 +870,8 @@ namespace libtorrent // downloads etc. // // This request will specifically update the ``num_complete`` and ``num_incomplete`` fields in - // the torrent_status_ struct once it completes. When it completes, it will generate a - // scrape_reply_alert_. If it fails, it will generate a scrape_failed_alert_. + // the torrent_status struct once it completes. When it completes, it will generate a + // scrape_reply_alert. If it fails, it will generate a scrape_failed_alert. void scrape_tracker() const; // ``set_upload_limit`` will limit the upload bandwidth used by this particular torrent to the @@ -899,8 +899,8 @@ namespace libtorrent // torrent. If the peer does not respond, or is not a member of this torrent, it will simply // be disconnected. No harm can be done by using this other than an unnecessary connection // attempt is made. If the torrent is uninitialized or in queued or checking mode, this - // will throw libtorrent_exception_. The second (optional) argument will be bitwised ORed into - // the source mask of this peer. Typically this is one of the source flags in peer_info_. + // will throw libtorrent_exception. The second (optional) argument will be bitwised ORed into + // the source mask of this peer. Typically this is one of the source flags in peer_info. // i.e. ``tracker``, ``pex``, ``dht`` etc. void connect_peer(tcp::endpoint const& adr, int source = 0) const; @@ -917,7 +917,7 @@ namespace libtorrent // connections are used up, incoming connections may be refused or poor connections may be closed. // This must be at least 2. The default is unlimited number of connections. If -1 is given to the // function, it means unlimited. There is also a global limit of the number of connections, set - // by ``connections_limit`` in session_settings_. + // by ``connections_limit`` in session_settings. // // ``max_connections()`` returns the current settings. void set_max_connections(int max_connections) const; @@ -1126,7 +1126,7 @@ namespace libtorrent 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() add_torrent()`_ when this torrent + // 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; @@ -1292,8 +1292,8 @@ namespace libtorrent // the size of a block, in bytes. A block is a sub piece, it // is the number of bytes that each piece request asks for and the number of - // bytes that each bit in the ``partial_piece_info``'s bitset represents - // (see `get_download_queue()`_). This is typically 16 kB, but it may be + // bytes that each bit in the ``partial_piece_info``'s bitset represents, + // see get_download_queue(). This is typically 16 kB, but it may be // larger if the pieces are larger. int block_size; @@ -1368,8 +1368,8 @@ namespace libtorrent // auto-managed, it will periodically be taken out of this state, in the // hope that the disk condition (be it disk full or permission errors) has // been resolved. If the torrent is not auto-managed, you have to explicitly - // take it out of the upload mode by calling `set_upload_mode()`_ on the - // torrent_handle_. + // take it out of the upload mode by calling set_upload_mode() on the + // torrent_handle. bool upload_mode; // true if the torrent is currently in share-mode, i.e.