premiere-libtorrent/docs/reference-Alerts.html

2500 lines
107 KiB
HTML

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<title>Alerts</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" />
<script type="text/javascript">
/* <![CDATA[ */
(function() {
var s = document.createElement('script'), t = document.getElementsByTagName('script')[0];
s.type = 'text/javascript';
s.async = true;
s.src = 'http://api.flattr.com/js/0.6/load.js?mode=auto';
t.parentNode.insertBefore(s, t);
})();
/* ]]> */
</script>
<link rel="stylesheet" href="style.css" type="text/css" />
<style type="text/css">
/* Hides from IE-mac \*/
* html pre { height: 1%; }
/* End hide from IE-mac */
</style>
</head>
<body>
<div class="document" id="alerts">
<div id="container">
<div id="headerNav">
<ul>
<li class="first"><a href="/">Home</a></li>
<li><a href="../../products.html">Products</a></li>
<li><a href="../../contact.html">Contact</a></li>
</ul>
</div>
<div id="header">
<div id="orange"></div>
<div id="logo"></div>
</div>
<div id="main">
<h1 class="title">Alerts</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference external" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>1.0.0</td></tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#alert" id="id236">alert</a></li>
<li><a class="reference internal" href="#torrent-alert" id="id237">torrent_alert</a></li>
<li><a class="reference internal" href="#peer-alert" id="id238">peer_alert</a></li>
<li><a class="reference internal" href="#tracker-alert" id="id239">tracker_alert</a></li>
<li><a class="reference internal" href="#torrent-added-alert" id="id240">torrent_added_alert</a></li>
<li><a class="reference internal" href="#torrent-removed-alert" id="id241">torrent_removed_alert</a></li>
<li><a class="reference internal" href="#read-piece-alert" id="id242">read_piece_alert</a></li>
<li><a class="reference internal" href="#file-completed-alert" id="id243">file_completed_alert</a></li>
<li><a class="reference internal" href="#file-renamed-alert" id="id244">file_renamed_alert</a></li>
<li><a class="reference internal" href="#file-rename-failed-alert" id="id245">file_rename_failed_alert</a></li>
<li><a class="reference internal" href="#performance-alert" id="id246">performance_alert</a></li>
<li><a class="reference internal" href="#state-changed-alert" id="id247">state_changed_alert</a></li>
<li><a class="reference internal" href="#tracker-error-alert" id="id248">tracker_error_alert</a></li>
<li><a class="reference internal" href="#tracker-warning-alert" id="id249">tracker_warning_alert</a></li>
<li><a class="reference internal" href="#scrape-reply-alert" id="id250">scrape_reply_alert</a></li>
<li><a class="reference internal" href="#scrape-failed-alert" id="id251">scrape_failed_alert</a></li>
<li><a class="reference internal" href="#tracker-reply-alert" id="id252">tracker_reply_alert</a></li>
<li><a class="reference internal" href="#dht-reply-alert" id="id253">dht_reply_alert</a></li>
<li><a class="reference internal" href="#tracker-announce-alert" id="id254">tracker_announce_alert</a></li>
<li><a class="reference internal" href="#hash-failed-alert" id="id255">hash_failed_alert</a></li>
<li><a class="reference internal" href="#peer-ban-alert" id="id256">peer_ban_alert</a></li>
<li><a class="reference internal" href="#peer-unsnubbed-alert" id="id257">peer_unsnubbed_alert</a></li>
<li><a class="reference internal" href="#peer-snubbed-alert" id="id258">peer_snubbed_alert</a></li>
<li><a class="reference internal" href="#peer-error-alert" id="id259">peer_error_alert</a></li>
<li><a class="reference internal" href="#peer-connect-alert" id="id260">peer_connect_alert</a></li>
<li><a class="reference internal" href="#peer-disconnected-alert" id="id261">peer_disconnected_alert</a></li>
<li><a class="reference internal" href="#invalid-request-alert" id="id262">invalid_request_alert</a></li>
<li><a class="reference internal" href="#torrent-finished-alert" id="id263">torrent_finished_alert</a></li>
<li><a class="reference internal" href="#piece-finished-alert" id="id264">piece_finished_alert</a></li>
<li><a class="reference internal" href="#request-dropped-alert" id="id265">request_dropped_alert</a></li>
<li><a class="reference internal" href="#block-timeout-alert" id="id266">block_timeout_alert</a></li>
<li><a class="reference internal" href="#block-finished-alert" id="id267">block_finished_alert</a></li>
<li><a class="reference internal" href="#block-downloading-alert" id="id268">block_downloading_alert</a></li>
<li><a class="reference internal" href="#unwanted-block-alert" id="id269">unwanted_block_alert</a></li>
<li><a class="reference internal" href="#storage-moved-alert" id="id270">storage_moved_alert</a></li>
<li><a class="reference internal" href="#storage-moved-failed-alert" id="id271">storage_moved_failed_alert</a></li>
<li><a class="reference internal" href="#torrent-deleted-alert" id="id272">torrent_deleted_alert</a></li>
<li><a class="reference internal" href="#torrent-delete-failed-alert" id="id273">torrent_delete_failed_alert</a></li>
<li><a class="reference internal" href="#save-resume-data-alert" id="id274">save_resume_data_alert</a></li>
<li><a class="reference internal" href="#save-resume-data-failed-alert" id="id275">save_resume_data_failed_alert</a></li>
<li><a class="reference internal" href="#torrent-paused-alert" id="id276">torrent_paused_alert</a></li>
<li><a class="reference internal" href="#torrent-resumed-alert" id="id277">torrent_resumed_alert</a></li>
<li><a class="reference internal" href="#torrent-checked-alert" id="id278">torrent_checked_alert</a></li>
<li><a class="reference internal" href="#url-seed-alert" id="id279">url_seed_alert</a></li>
<li><a class="reference internal" href="#file-error-alert" id="id280">file_error_alert</a></li>
<li><a class="reference internal" href="#metadata-failed-alert" id="id281">metadata_failed_alert</a></li>
<li><a class="reference internal" href="#metadata-received-alert" id="id282">metadata_received_alert</a></li>
<li><a class="reference internal" href="#udp-error-alert" id="id283">udp_error_alert</a></li>
<li><a class="reference internal" href="#external-ip-alert" id="id284">external_ip_alert</a></li>
<li><a class="reference internal" href="#listen-failed-alert" id="id285">listen_failed_alert</a></li>
<li><a class="reference internal" href="#listen-succeeded-alert" id="id286">listen_succeeded_alert</a></li>
<li><a class="reference internal" href="#portmap-error-alert" id="id287">portmap_error_alert</a></li>
<li><a class="reference internal" href="#portmap-alert" id="id288">portmap_alert</a></li>
<li><a class="reference internal" href="#portmap-log-alert" id="id289">portmap_log_alert</a></li>
<li><a class="reference internal" href="#fastresume-rejected-alert" id="id290">fastresume_rejected_alert</a></li>
<li><a class="reference internal" href="#peer-blocked-alert" id="id291">peer_blocked_alert</a></li>
<li><a class="reference internal" href="#dht-announce-alert" id="id292">dht_announce_alert</a></li>
<li><a class="reference internal" href="#dht-get-peers-alert" id="id293">dht_get_peers_alert</a></li>
<li><a class="reference internal" href="#stats-alert" id="id294">stats_alert</a></li>
<li><a class="reference internal" href="#cache-flushed-alert" id="id295">cache_flushed_alert</a></li>
<li><a class="reference internal" href="#anonymous-mode-alert" id="id296">anonymous_mode_alert</a></li>
<li><a class="reference internal" href="#lsd-peer-alert" id="id297">lsd_peer_alert</a></li>
<li><a class="reference internal" href="#trackerid-alert" id="id298">trackerid_alert</a></li>
<li><a class="reference internal" href="#dht-bootstrap-alert" id="id299">dht_bootstrap_alert</a></li>
<li><a class="reference internal" href="#rss-alert" id="id300">rss_alert</a></li>
<li><a class="reference internal" href="#torrent-error-alert" id="id301">torrent_error_alert</a></li>
<li><a class="reference internal" href="#torrent-need-cert-alert" id="id302">torrent_need_cert_alert</a></li>
<li><a class="reference internal" href="#incoming-connection-alert" id="id303">incoming_connection_alert</a></li>
<li><a class="reference internal" href="#add-torrent-alert" id="id304">add_torrent_alert</a></li>
<li><a class="reference internal" href="#state-update-alert" id="id305">state_update_alert</a></li>
<li><a class="reference internal" href="#torrent-update-alert" id="id306">torrent_update_alert</a></li>
<li><a class="reference internal" href="#rss-item-alert" id="id307">rss_item_alert</a></li>
<li><a class="reference internal" href="#dht-error-alert" id="id308">dht_error_alert</a></li>
<li><a class="reference internal" href="#dht-immutable-item-alert" id="id309">dht_immutable_item_alert</a></li>
<li><a class="reference internal" href="#dht-mutable-item-alert" id="id310">dht_mutable_item_alert</a></li>
<li><a class="reference internal" href="#dht-put-alert" id="id311">dht_put_alert</a></li>
<li><a class="reference internal" href="#i2p-alert" id="id312">i2p_alert</a></li>
</ul>
</div>
<p>The <a class="reference external" href="reference-Session.html#pop_alert()">pop_alert()</a> function on <a class="reference external" href="reference-Session.html#session">session</a> is the interface for retrieving
alerts, warnings, messages and errors from libtorrent. If no alerts have
been posted by libtorrent <a class="reference external" href="reference-Session.html#pop_alert()">pop_alert()</a> will return a default initialized
<tt class="docutils literal"><span class="pre">std::auto_ptr</span></tt> object. If there is an <a class="reference external" href="reference-Alerts.html#alert">alert</a> in libtorrent's queue, the <a class="reference external" href="reference-Alerts.html#alert">alert</a>
from the front of the queue is popped and returned.
You can then use the <a class="reference external" href="reference-Alerts.html#alert">alert</a> object and query</p>
<p>By default, only errors are reported. <a class="reference external" href="reference-Session.html#set_alert_mask()">set_alert_mask()</a> can be
used to specify which kinds of events should be reported. The <a class="reference external" href="reference-Alerts.html#alert">alert</a> mask
is comprised by bits from the <a class="reference external" href="reference-Alerts.html#category_t">category_t</a> enum.</p>
<p>Every <a class="reference external" href="reference-Alerts.html#alert">alert</a> belongs to one or more category. There is a small cost involved in posting alerts. Only
alerts that belong to an enabled category are posted. Setting the <a class="reference external" href="reference-Alerts.html#alert">alert</a> bitmask to 0 will disable
all alerts (except those that are non-discardable).</p>
<p>There are other <a class="reference external" href="reference-Alerts.html#alert">alert</a> base classes that some alerts derive from, all the
alerts that are generated for a specific torrent are derived from <a class="reference external" href="reference-Alerts.html#torrent_alert">torrent_alert</a>,
and tracker events derive from <a class="reference external" href="reference-Alerts.html#tracker_alert">tracker_alert</a>.</p>
<a name="alert"></a><div class="section" id="alert">
<h1>alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert.hpp">libtorrent/alert.hpp</a>&quot;</p>
<p>The <tt class="docutils literal">alert</tt> class is the base class that specific messages are derived from.</p>
<pre class="literal-block">
class alert
{
ptime <strong>timestamp</strong> () const;
virtual int <strong>type</strong> () const = 0;
virtual char const* <strong>what</strong> () const = 0;
virtual std::string <strong>message</strong> () const = 0;
virtual int <strong>category</strong> () const = 0;
virtual bool <strong>discardable</strong> () const;
virtual std::auto_ptr&lt;alert&gt; <strong>clone</strong> () const = 0;
enum category_t
{
error_notification,
peer_notification,
port_mapping_notification,
storage_notification,
tracker_notification,
debug_notification,
status_notification,
progress_notification,
ip_block_notification,
performance_warning,
dht_notification,
stats_notification,
rss_notification,
all_categories,
};
};
</pre>
<a name="timestamp()"></a><div class="section" id="timestamp">
<h2>timestamp()</h2>
<pre class="literal-block">
ptime <strong>timestamp</strong> () const;
</pre>
<p>a timestamp is automatically created in the constructor</p>
<a name="type()"></a></div>
<div class="section" id="type">
<h2>type()</h2>
<pre class="literal-block">
virtual int <strong>type</strong> () const = 0;
</pre>
<p>returns an integer that is unique to this <a class="reference external" href="reference-Alerts.html#alert">alert</a> type. It can be
compared against a specific <a class="reference external" href="reference-Alerts.html#alert">alert</a> by querying a static constant called <tt class="docutils literal">alert_type</tt>
in the <a class="reference external" href="reference-Alerts.html#alert">alert</a>. It can be used to determine the run-time type of an alert* in
order to cast to that <a class="reference external" href="reference-Alerts.html#alert">alert</a> type and access specific members.</p>
<p>e.g:</p>
<pre class="literal-block">
std::auto_ptr&lt;alert&gt; a = ses.pop_alert();
switch (a-&gt;type())
{
case read_piece_alert::alert_type:
{
read_piece_alert* p = (read_piece_alert*)a.get();
if (p-&gt;ec) {
// read_piece failed
break;
}
// use p
break;
}
case file_renamed_alert::alert_type:
{
// etc...
}
}
</pre>
<a name="what()"></a></div>
<div class="section" id="what">
<h2>what()</h2>
<pre class="literal-block">
virtual char const* <strong>what</strong> () const = 0;
</pre>
<p>returns a string literal describing the type of the <a class="reference external" href="reference-Alerts.html#alert">alert</a>. It does
not include any information that might be bundled with the <a class="reference external" href="reference-Alerts.html#alert">alert</a>.</p>
<a name="message()"></a></div>
<div class="section" id="message">
<h2>message()</h2>
<pre class="literal-block">
virtual std::string <strong>message</strong> () const = 0;
</pre>
<p>generate a string describing the <a class="reference external" href="reference-Alerts.html#alert">alert</a> and the information bundled
with it. This is mainly intended for debug and development use. It is not suitable
to use this for applications that may be localized. Instead, handle each <a class="reference external" href="reference-Alerts.html#alert">alert</a>
type individually and extract and render the information from the <a class="reference external" href="reference-Alerts.html#alert">alert</a> depending
on the locale.</p>
<a name="category()"></a></div>
<div class="section" id="category">
<h2>category()</h2>
<pre class="literal-block">
virtual int <strong>category</strong> () const = 0;
</pre>
<p>returns a bitmask specifying which categories this <a class="reference external" href="reference-Alerts.html#alert">alert</a> belong to.</p>
<a name="discardable()"></a></div>
<div class="section" id="discardable">
<h2>discardable()</h2>
<pre class="literal-block">
virtual bool <strong>discardable</strong> () const;
</pre>
<p>determines whether or not an <a class="reference external" href="reference-Alerts.html#alert">alert</a> is allowed to be discarded
when the <a class="reference external" href="reference-Alerts.html#alert">alert</a> queue is full. There are a few alerts which may not be discared,
since they would break the user contract, such as <a class="reference external" href="reference-Alerts.html#save_resume_data_alert">save_resume_data_alert</a>.</p>
<a name="clone()"></a></div>
<div class="section" id="clone">
<h2>clone()</h2>
<pre class="literal-block">
virtual std::auto_ptr&lt;alert&gt; <strong>clone</strong> () const = 0;
</pre>
<p>returns a pointer to a copy of the <a class="reference external" href="reference-Alerts.html#alert">alert</a>.</p>
<a name="category_t"></a></div>
<div class="section" id="enum-category-t">
<h2>enum category_t</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert.hpp">libtorrent/alert.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="25%" />
<col width="11%" />
<col width="64%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">value</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>error_notification</td>
<td>1</td>
<td><p class="first">Enables alerts that report an error. This includes:</p>
<ul class="last simple">
<li>tracker errors</li>
<li>tracker warnings</li>
<li>file errors</li>
<li>resume data failures</li>
<li>web seed errors</li>
<li>.torrent files errors</li>
<li>listen socket errors</li>
<li>port mapping errors</li>
</ul>
</td>
</tr>
<tr><td>peer_notification</td>
<td>2</td>
<td>Enables alerts when peers send invalid requests, get banned or
snubbed.</td>
</tr>
<tr><td>port_mapping_notification</td>
<td>4</td>
<td>Enables alerts for port mapping events. For NAT-PMP and UPnP.</td>
</tr>
<tr><td>storage_notification</td>
<td>8</td>
<td>Enables alerts for events related to the storage. File errors and
synchronization events for moving the storage, renaming files etc.</td>
</tr>
<tr><td>tracker_notification</td>
<td>16</td>
<td>Enables all tracker events. Includes announcing to trackers,
receiving responses, warnings and errors.</td>
</tr>
<tr><td>debug_notification</td>
<td>32</td>
<td>Low level alerts for when peers are connected and disconnected.</td>
</tr>
<tr><td>status_notification</td>
<td>64</td>
<td>Enables alerts for when a torrent or the <a class="reference external" href="reference-Session.html#session">session</a> changes state.</td>
</tr>
<tr><td>progress_notification</td>
<td>128</td>
<td>Alerts for when blocks are requested and completed. Also when
pieces are completed.</td>
</tr>
<tr><td>ip_block_notification</td>
<td>256</td>
<td>Alerts when a peer is blocked by the ip blocker or port blocker.</td>
</tr>
<tr><td>performance_warning</td>
<td>512</td>
<td>Alerts when some limit is reached that might limit the download
or upload rate.</td>
</tr>
<tr><td>dht_notification</td>
<td>1024</td>
<td>Alerts on events in the DHT node. For incoming searches or
bootstrapping being done etc.</td>
</tr>
<tr><td>stats_notification</td>
<td>2048</td>
<td>If you enable these alerts, you will receive a <a class="reference external" href="reference-Alerts.html#stats_alert">stats_alert</a>
approximately once every second, for every active torrent.
These alerts contain all statistics counters for the interval since
the lasts stats <a class="reference external" href="reference-Alerts.html#alert">alert</a>.</td>
</tr>
<tr><td>rss_notification</td>
<td>4096</td>
<td>Alerts on RSS related events, like feeds being updated, feed error
conditions and successful RSS feed updates. Enabling this categoty
will make you receive <a class="reference external" href="reference-Alerts.html#rss_alert">rss_alert</a> alerts.</td>
</tr>
<tr><td>all_categories</td>
<td>2147483647</td>
<td><p class="first">The full bitmask, representing all available categories.</p>
<p class="last">since the enum is signed, make sure this isn't
interpreted as -1. For instance, boost.python
does that and fails when assigning it to an
unsigned parameter.</p>
</td>
</tr>
</tbody>
</table>
<a name="torrent_alert"></a></div>
</div>
<div class="section" id="torrent-alert">
<h1>torrent_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This is a base class for alerts that are associated with a
specific torrent. It contains a handle to the torrent.</p>
<pre class="literal-block">
struct torrent_alert: alert
{
torrent_handle handle;
};
</pre>
<a name="handle"></a><dl class="docutils">
<dt>handle</dt>
<dd>The <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> pointing to the torrent this
<a class="reference external" href="reference-Alerts.html#alert">alert</a> is associated with.</dd>
</dl>
<a name="peer_alert"></a></div>
<div class="section" id="peer-alert">
<h1>peer_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>The peer <a class="reference external" href="reference-Alerts.html#alert">alert</a> is a base class for alerts that refer to a specific peer. It includes all
the information to identify the peer. i.e. <tt class="docutils literal">ip</tt> and <tt class="docutils literal"><span class="pre">peer-id</span></tt>.</p>
<pre class="literal-block">
struct peer_alert: torrent_alert
{
virtual int <strong>category</strong> () const;
virtual std::string <strong>message</strong> () const;
const static int alert_type = 2;
const static int static_category = alert::peer_notification;
tcp::endpoint ip;
peer_id pid;
};
</pre>
<a name="ip"></a><dl class="docutils">
<dt>ip</dt>
<dd>The peer's IP address and port.</dd>
</dl>
<a name="pid"></a><dl class="docutils">
<dt>pid</dt>
<dd>the peer ID, if known.</dd>
</dl>
<a name="tracker_alert"></a></div>
<div class="section" id="tracker-alert">
<h1>tracker_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This is a base class used for alerts that are associated with a
specific tracker. It derives from <a class="reference external" href="reference-Alerts.html#torrent_alert">torrent_alert</a> since a tracker
is also associated with a specific torrent.</p>
<pre class="literal-block">
struct tracker_alert: torrent_alert
{
virtual int <strong>category</strong> () const;
virtual std::string <strong>message</strong> () const;
const static int alert_type = 3;
const static int static_category = alert::tracker_notification;
std::string url;
};
</pre>
<a name="url"></a><dl class="docutils">
<dt>url</dt>
<dd>The tracker URL</dd>
</dl>
<a name="torrent_added_alert"></a></div>
<div class="section" id="torrent-added-alert">
<h1>torrent_added_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>The <tt class="docutils literal">torrent_added_alert</tt> 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 <tt class="docutils literal">status_notification</tt> bit is set in the alert_mask.</p>
<pre class="literal-block">
struct torrent_added_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::status_notification;
};
</pre>
<a name="torrent_removed_alert"></a></div>
<div class="section" id="torrent-removed-alert">
<h1>torrent_removed_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>The <tt class="docutils literal">torrent_removed_alert</tt> 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 <tt class="docutils literal">status_notification</tt> bit is set in the alert_mask.</p>
<p>Even though the <tt class="docutils literal">handle</tt> 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.</p>
<p>The <tt class="docutils literal">torrent_handle</tt> acts as a <tt class="docutils literal">weak_ptr</tt>, even though its object no
longer exists, it can still compare equal to another weak pointer which
points to the same non-existent object.</p>
<pre class="literal-block">
struct torrent_removed_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::status_notification;
sha1_hash info_hash;
};
</pre>
<a name="read_piece_alert"></a></div>
<div class="section" id="read-piece-alert">
<h1>read_piece_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted when the asynchronous read operation initiated by
a call to <a class="reference external" href="reference-Core.html#read_piece()">torrent_handle::read_piece()</a> is completed. If the read failed, the torrent
is paused and an error state is set and the buffer member of the <a class="reference external" href="reference-Alerts.html#alert">alert</a>
is 0. If successful, <tt class="docutils literal">buffer</tt> points to a buffer containing all the data
of the piece. <tt class="docutils literal">piece</tt> is the piece index that was read. <tt class="docutils literal">size</tt> is the
number of bytes that was read.</p>
<p>If the operation fails, ec will indicat what went wrong.</p>
<pre class="literal-block">
struct read_piece_alert: torrent_alert
{
virtual bool <strong>discardable</strong> () const;
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::storage_notification;
error_code ec;
boost::shared_array&lt;char&gt; buffer;
int piece;
int size;
};
</pre>
<a name="file_completed_alert"></a></div>
<div class="section" id="file-completed-alert">
<h1>file_completed_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This is posted whenever an individual file completes its download. i.e.
All pieces overlapping this file have passed their hash check.</p>
<pre class="literal-block">
struct file_completed_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::progress_notification;
int index;
};
</pre>
<a name="index"></a><dl class="docutils">
<dt>index</dt>
<dd>refers to the index of the file that completed.</dd>
</dl>
<a name="file_renamed_alert"></a></div>
<div class="section" id="file-renamed-alert">
<h1>file_renamed_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This is posted as a response to a <a class="reference external" href="reference-Core.html#rename_file()">torrent_handle::rename_file()</a> call, if the rename
operation succeeds.</p>
<pre class="literal-block">
struct file_renamed_alert: torrent_alert
{
virtual bool <strong>discardable</strong> () const;
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::storage_notification;
std::string name;
int index;
};
</pre>
<a name="index"></a><dl class="docutils">
<dt>index</dt>
<dd>refers to the index of the file that was renamed,
<tt class="docutils literal">name</tt> is the new name of the file.</dd>
</dl>
<a name="file_rename_failed_alert"></a></div>
<div class="section" id="file-rename-failed-alert">
<h1>file_rename_failed_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This is posted as a response to a <a class="reference external" href="reference-Core.html#rename_file()">torrent_handle::rename_file()</a> call, if the rename
operation failed.</p>
<pre class="literal-block">
struct file_rename_failed_alert: torrent_alert
{
virtual bool <strong>discardable</strong> () const;
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::storage_notification;
int index;
error_code error;
};
</pre>
<a name="index"></a>
<a name="error"></a><dl class="docutils">
<dt>index error</dt>
<dd>refers to the index of the file that was supposed to be renamed,
<tt class="docutils literal">error</tt> is the error code returned from the filesystem.</dd>
</dl>
<a name="performance_alert"></a></div>
<div class="section" id="performance-alert">
<h1>performance_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a limit is reached that might have a negative impact on
upload or download rate performance.</p>
<pre class="literal-block">
struct performance_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
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,
bittyrant_with_no_uplimit,
too_few_outgoing_ports,
too_few_file_descriptors,
num_warnings,
};
const static int static_category = alert::performance_warning;
performance_warning_t warning_code;
};
</pre>
<a name="performance_warning_t"></a><div class="section" id="enum-performance-warning-t">
<h2>enum performance_warning_t</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="27%" />
<col width="5%" />
<col width="68%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">value</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>outstanding_disk_buffer_limit_reached</td>
<td>0</td>
<td>This warning means that the number of bytes queued to be written to disk
exceeds the max disk byte queue setting (<tt class="docutils literal"><span class="pre">session_settings::max_queued_disk_bytes</span></tt>).
This might restrict the download rate, by not queuing up enough write jobs
to the disk I/O thread. When this <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted, peer connections are
temporarily stopped from downloading, until the queued disk bytes have fallen
below the limit again. Unless your <tt class="docutils literal">max_queued_disk_bytes</tt> setting is already
high, you might want to increase it to get better performance.</td>
</tr>
<tr><td>outstanding_request_limit_reached</td>
<td>1</td>
<td>This is posted when libtorrent would like to send more requests to a peer,
but it's limited by <tt class="docutils literal"><span class="pre">session_settings::max_out_request_queue</span></tt>. The queue length
libtorrent is trying to achieve is determined by the download rate and the
assumed round-trip-time (<tt class="docutils literal"><span class="pre">session_settings::request_queue_time</span></tt>). 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 <a class="reference external" href="reference-Alerts.html#alert">alert</a>
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 <tt class="docutils literal">max_out_request_queue</tt>
setting.</td>
</tr>
<tr><td>upload_limit_too_low</td>
<td>2</td>
<td>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.</td>
</tr>
<tr><td>download_limit_too_low</td>
<td>3</td>
<td>This is the same warning as <tt class="docutils literal">upload_limit_too_low</tt> 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.</td>
</tr>
<tr><td>send_buffer_watermark_too_low</td>
<td>4</td>
<td><p class="first">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:</p>
<pre class="literal-block">
min(512, max(upload_rate * send_buffer_watermark_factor / 100, send_buffer_watermark))
</pre>
<p class="last">If you receive this <a class="reference external" href="reference-Alerts.html#alert">alert</a>, you migth want to either increase your <tt class="docutils literal">send_buffer_watermark</tt>
or <tt class="docutils literal">send_buffer_watermark_factor</tt>.</p>
</td>
</tr>
<tr><td>too_many_optimistic_unchoke_slots</td>
<td>5</td>
<td>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.</td>
</tr>
<tr><td>too_high_disk_queue_limit</td>
<td>6</td>
<td>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 <tt class="docutils literal">max_queued_disk_bytes</tt> or increase <tt class="docutils literal">cache_size</tt>.</td>
</tr>
<tr><td>bittyrant_with_no_uplimit</td>
<td>7</td>
<td>&nbsp;</td>
</tr>
<tr><td>too_few_outgoing_ports</td>
<td>8</td>
<td>This is generated if outgoing peer connections are failing because of <em>address in use</em>
errors, indicating that <tt class="docutils literal"><span class="pre">session_settings::outgoing_ports</span></tt> is set and is too small of
a range. Consider not using the <tt class="docutils literal">outgoing_ports</tt> setting at all, or widen the range to
include more ports.</td>
</tr>
<tr><td>too_few_file_descriptors</td>
<td>9</td>
<td>&nbsp;</td>
</tr>
<tr><td>num_warnings</td>
<td>10</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<a name="state_changed_alert"></a></div>
</div>
<div class="section" id="state-changed-alert">
<h1>state_changed_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>Generated whenever a torrent changes its state.</p>
<pre class="literal-block">
struct state_changed_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::status_notification;
torrent_status::state_t state;
torrent_status::state_t prev_state;
};
</pre>
<a name="state"></a><dl class="docutils">
<dt>state</dt>
<dd>the new state of the torrent.</dd>
</dl>
<a name="prev_state"></a><dl class="docutils">
<dt>prev_state</dt>
<dd>the previous state.</dd>
</dl>
<a name="tracker_error_alert"></a></div>
<div class="section" id="tracker-error-alert">
<h1>tracker_error_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated on tracker time outs, premature disconnects, invalid response or
a HTTP response other than &quot;200 OK&quot;. From the <a class="reference external" href="reference-Alerts.html#alert">alert</a> you can get the handle to the torrent
the tracker belongs to.</p>
<p>The <tt class="docutils literal">times_in_row</tt> member says how many times in a row this tracker has failed.
<tt class="docutils literal">status_code</tt> 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.</p>
<pre class="literal-block">
struct tracker_error_alert: tracker_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::tracker_notification | alert::error_notification;
int times_in_row;
int status_code;
error_code error;
std::string msg;
};
</pre>
<a name="tracker_warning_alert"></a></div>
<div class="section" id="tracker-warning-alert">
<h1>tracker_warning_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> 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.</p>
<pre class="literal-block">
struct tracker_warning_alert: tracker_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::tracker_notification | alert::error_notification;
std::string msg;
};
</pre>
<a name="msg"></a><dl class="docutils">
<dt>msg</dt>
<dd>contains the warning message from the tracker.</dd>
</dl>
<a name="scrape_reply_alert"></a></div>
<div class="section" id="scrape-reply-alert">
<h1>scrape_reply_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a scrape request succeeds.</p>
<pre class="literal-block">
struct scrape_reply_alert: tracker_alert
{
virtual std::string <strong>message</strong> () const;
int incomplete;
int complete;
};
</pre>
<a name="incomplete"></a>
<a name="complete"></a><dl class="docutils">
<dt>incomplete complete</dt>
<dd>the data returned in the scrape response. These numbers
may be -1 if the reponse was malformed.</dd>
</dl>
<a name="scrape_failed_alert"></a></div>
<div class="section" id="scrape-failed-alert">
<h1>scrape_failed_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>If a scrape request fails, this <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated. This might be due
to the tracker timing out, refusing connection or returning an http response
code indicating an error.</p>
<pre class="literal-block">
struct scrape_failed_alert: tracker_alert
{
<strong>scrape_failed_alert</strong> (torrent_handle const&amp; h
, std::string const&amp; u
, std::string const&amp; m);
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::tracker_notification | alert::error_notification;
std::string msg;
};
</pre>
<a name="msg"></a><dl class="docutils">
<dt>msg</dt>
<dd>contains a message describing the error.</dd>
</dl>
<a name="tracker_reply_alert"></a></div>
<div class="section" id="tracker-reply-alert">
<h1>tracker_reply_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> 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.</p>
<pre class="literal-block">
struct tracker_reply_alert: tracker_alert
{
virtual std::string <strong>message</strong> () const;
int num_peers;
};
</pre>
<a name="num_peers"></a><dl class="docutils">
<dt>num_peers</dt>
<dd>tells how many peers the tracker returned in this response. This is
not expected to be more thant the <tt class="docutils literal">num_want</tt> settings. These are not necessarily
all new peers, some of them may already be connected.</dd>
</dl>
<a name="dht_reply_alert"></a></div>
<div class="section" id="dht-reply-alert">
<h1>dht_reply_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated each time the DHT receives peers from a node. <tt class="docutils literal">num_peers</tt>
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.</p>
<pre class="literal-block">
struct dht_reply_alert: tracker_alert
{
virtual std::string <strong>message</strong> () const;
int num_peers;
};
</pre>
<a name="tracker_announce_alert"></a></div>
<div class="section" id="tracker-announce-alert">
<h1>tracker_announce_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated each time a tracker announce is sent (or attempted to be sent).
There are no extra data members in this <a class="reference external" href="reference-Alerts.html#alert">alert</a>. The url can be found in the base class
however.</p>
<pre class="literal-block">
struct tracker_announce_alert: tracker_alert
{
virtual std::string <strong>message</strong> () const;
int event;
};
</pre>
<a name="event"></a><dl class="docutils">
<dt>event</dt>
<dd><p class="first">specifies what event was sent to the tracker. It is defined as:</p>
<ol class="last arabic simple" start="0">
<li>None</li>
<li>Completed</li>
<li>Started</li>
<li>Stopped</li>
</ol>
</dd>
</dl>
<a name="hash_failed_alert"></a></div>
<div class="section" id="hash-failed-alert">
<h1>hash_failed_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> 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 <a class="reference external" href="reference-Alerts.html#alert">alert</a>.</p>
<pre class="literal-block">
struct hash_failed_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::status_notification;
int piece_index;
};
</pre>
<a name="peer_ban_alert"></a></div>
<div class="section" id="peer-ban-alert">
<h1>peer_ban_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a peer is banned because it has sent too many corrupt pieces
to us. <tt class="docutils literal">ip</tt> is the endpoint to the peer that was banned.</p>
<pre class="literal-block">
struct peer_ban_alert: peer_alert
{
virtual std::string <strong>message</strong> () const;
};
</pre>
<a name="peer_unsnubbed_alert"></a></div>
<div class="section" id="peer-unsnubbed-alert">
<h1>peer_unsnubbed_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a peer is unsnubbed. Essentially when it was snubbed for stalling
sending data, and now it started sending data again.</p>
<pre class="literal-block">
struct peer_unsnubbed_alert: peer_alert
{
virtual std::string <strong>message</strong> () const;
};
</pre>
<a name="peer_snubbed_alert"></a></div>
<div class="section" id="peer-snubbed-alert">
<h1>peer_snubbed_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a peer is snubbed, when it stops sending data when we request
it.</p>
<pre class="literal-block">
struct peer_snubbed_alert: peer_alert
{
virtual std::string <strong>message</strong> () const;
};
</pre>
<a name="peer_error_alert"></a></div>
<div class="section" id="peer-error-alert">
<h1>peer_error_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> 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 <a class="reference external" href="reference-Alerts.html#alert">alert</a>, to identify it.</p>
<pre class="literal-block">
struct peer_error_alert: peer_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::peer_notification;
error_code error;
};
</pre>
<a name="error"></a><dl class="docutils">
<dt>error</dt>
<dd>tells you what error caused this <a class="reference external" href="reference-Alerts.html#alert">alert</a>.</dd>
</dl>
<a name="peer_connect_alert"></a></div>
<div class="section" id="peer-connect-alert">
<h1>peer_connect_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted every time an outgoing peer connect attempts succeeds.</p>
<pre class="literal-block">
struct peer_connect_alert: peer_alert
{
virtual std::string <strong>message</strong> () const;;
const static int static_category = alert::debug_notification;
int socket_type;
};
</pre>
<a name="peer_disconnected_alert"></a></div>
<div class="section" id="peer-disconnected-alert">
<h1>peer_disconnected_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a peer is disconnected for any reason (other than the ones
covered by <a class="reference external" href="reference-Alerts.html#peer_error_alert">peer_error_alert</a> ).</p>
<pre class="literal-block">
struct peer_disconnected_alert: peer_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::debug_notification;
error_code error;
};
</pre>
<a name="error"></a><dl class="docutils">
<dt>error</dt>
<dd>tells you what error caused peer to disconnect.</dd>
</dl>
<a name="invalid_request_alert"></a></div>
<div class="section" id="invalid-request-alert">
<h1>invalid_request_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This is a debug <a class="reference external" href="reference-Alerts.html#alert">alert</a> that is generated by an incoming invalid piece request.
<tt class="docutils literal">ip</tt> is the address of the peer and the <tt class="docutils literal">request</tt> is the actual incoming
request from the peer. See <a class="reference external" href="reference-Core.html#peer_request">peer_request</a> for more info.</p>
<pre class="literal-block">
struct invalid_request_alert: peer_alert
{
virtual std::string <strong>message</strong> () const;
peer_request request;
};
</pre>
<a name="torrent_finished_alert"></a></div>
<div class="section" id="torrent-finished-alert">
<h1>torrent_finished_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a torrent switches from being a downloader to a seed.
It will only be generated once per torrent. It contains a <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> to the
torrent in question.</p>
<pre class="literal-block">
struct torrent_finished_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::status_notification;
};
</pre>
<a name="piece_finished_alert"></a></div>
<div class="section" id="piece-finished-alert">
<h1>piece_finished_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>this <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted every time a piece completes downloading
and passes the hash check. This <a class="reference external" href="reference-Alerts.html#alert">alert</a> derives from <a class="reference external" href="reference-Alerts.html#torrent_alert">torrent_alert</a>
which contains the <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> to the torrent the piece belongs to.</p>
<pre class="literal-block">
struct piece_finished_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::progress_notification;
int piece_index;
};
</pre>
<a name="piece_index"></a><dl class="docutils">
<dt>piece_index</dt>
<dd>the index of the piece that finished</dd>
</dl>
<a name="request_dropped_alert"></a></div>
<div class="section" id="request-dropped-alert">
<h1>request_dropped_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a peer rejects or ignores a piece request.</p>
<pre class="literal-block">
struct request_dropped_alert: peer_alert
{
virtual std::string <strong>message</strong> () const;
| alert::peer_notification;
int block_index;
int piece_index;
};
</pre>
<a name="block_timeout_alert"></a></div>
<div class="section" id="block-timeout-alert">
<h1>block_timeout_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a block request times out.</p>
<pre class="literal-block">
struct block_timeout_alert: peer_alert
{
virtual std::string <strong>message</strong> () const;
| alert::peer_notification;
int block_index;
int piece_index;
};
</pre>
<a name="block_finished_alert"></a></div>
<div class="section" id="block-finished-alert">
<h1>block_finished_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a block request receives a response.</p>
<pre class="literal-block">
struct block_finished_alert: peer_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::progress_notification;
int block_index;
int piece_index;
};
</pre>
<a name="block_downloading_alert"></a></div>
<div class="section" id="block-downloading-alert">
<h1>block_downloading_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a block request is sent to a peer.</p>
<pre class="literal-block">
struct block_downloading_alert: peer_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::progress_notification;
char const* peer_speedmsg;
int block_index;
int piece_index;
};
</pre>
<a name="unwanted_block_alert"></a></div>
<div class="section" id="unwanted-block-alert">
<h1>unwanted_block_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a block is received that was not requested or
whose request timed out.</p>
<pre class="literal-block">
struct unwanted_block_alert: peer_alert
{
virtual std::string <strong>message</strong> () const;
int block_index;
int piece_index;
};
</pre>
<a name="storage_moved_alert"></a></div>
<div class="section" id="storage-moved-alert">
<h1>storage_moved_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>The <tt class="docutils literal">storage_moved_alert</tt> is generated when all the disk IO has completed and the
files have been moved, as an effect of a call to <tt class="docutils literal"><span class="pre">torrent_handle::move_storage</span></tt>. This
is useful to synchronize with the actual disk. The <tt class="docutils literal">path</tt> member is the new path of
the storage.</p>
<pre class="literal-block">
struct storage_moved_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::storage_notification;
std::string path;
};
</pre>
<a name="storage_moved_failed_alert"></a></div>
<div class="section" id="storage-moved-failed-alert">
<h1>storage_moved_failed_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>The <tt class="docutils literal">storage_moved_failed_alert</tt> is generated when an attempt to move the storage,
via <a class="reference external" href="reference-Core.html#move_storage()">torrent_handle::move_storage()</a>, fails.</p>
<pre class="literal-block">
struct storage_moved_failed_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::storage_notification;
error_code error;
};
</pre>
<a name="torrent_deleted_alert"></a></div>
<div class="section" id="torrent-deleted-alert">
<h1>torrent_deleted_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a request to delete the files of a torrent complete.</p>
<p>The <tt class="docutils literal">info_hash</tt> is the info-hash of the torrent that was just deleted. Most of
the time the <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> in the <tt class="docutils literal">torrent_alert</tt> will be invalid by the time
this <a class="reference external" href="reference-Alerts.html#alert">alert</a> arrives, since the torrent is being deleted. The <tt class="docutils literal">info_hash</tt> member
is hence the main way of identifying which torrent just completed the delete.</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted in the <tt class="docutils literal">storage_notification</tt> category, and that bit
needs to be set in the alert_mask.</p>
<pre class="literal-block">
struct torrent_deleted_alert: torrent_alert
{
virtual bool <strong>discardable</strong> () const;
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::storage_notification;
sha1_hash info_hash;
};
</pre>
<a name="torrent_delete_failed_alert"></a></div>
<div class="section" id="torrent-delete-failed-alert">
<h1>torrent_delete_failed_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a request to delete the files of a torrent fails.
Just removing a torrent from the <a class="reference external" href="reference-Session.html#session">session</a> cannot fail</p>
<pre class="literal-block">
struct torrent_delete_failed_alert: torrent_alert
{
virtual bool <strong>discardable</strong> () const;
virtual std::string <strong>message</strong> () const;
| alert::error_notification;
error_code error;
sha1_hash info_hash;
};
</pre>
<a name="error"></a><dl class="docutils">
<dt>error</dt>
<dd>tells you why it failed.</dd>
</dl>
<a name="info_hash"></a><dl class="docutils">
<dt>info_hash</dt>
<dd>the info hash of the torrent whose files failed to be deleted</dd>
</dl>
<a name="save_resume_data_alert"></a></div>
<div class="section" id="save-resume-data-alert">
<h1>save_resume_data_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated as a response to a <tt class="docutils literal"><span class="pre">torrent_handle::save_resume_data</span></tt> request.
It is generated once the disk IO thread is done writing the state for this torrent.</p>
<pre class="literal-block">
struct save_resume_data_alert: torrent_alert
{
virtual bool <strong>discardable</strong> () const;
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::storage_notification;
boost::shared_ptr&lt;entry&gt; resume_data;
};
</pre>
<a name="resume_data"></a><dl class="docutils">
<dt>resume_data</dt>
<dd>points to the resume data.</dd>
</dl>
<a name="save_resume_data_failed_alert"></a></div>
<div class="section" id="save-resume-data-failed-alert">
<h1>save_resume_data_failed_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated instead of <tt class="docutils literal">save_resume_data_alert</tt> if there was an error
generating the resume data. <tt class="docutils literal">error</tt> describes what went wrong.</p>
<pre class="literal-block">
struct save_resume_data_failed_alert: torrent_alert
{
virtual bool <strong>discardable</strong> () const;
virtual std::string <strong>message</strong> () const;
| alert::error_notification;
error_code error;
};
</pre>
<a name="torrent_paused_alert"></a></div>
<div class="section" id="torrent-paused-alert">
<h1>torrent_paused_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated as a response to a <tt class="docutils literal"><span class="pre">torrent_handle::pause</span></tt> 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.</p>
<pre class="literal-block">
struct torrent_paused_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::status_notification;
};
</pre>
<a name="torrent_resumed_alert"></a></div>
<div class="section" id="torrent-resumed-alert">
<h1>torrent_resumed_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated as a response to a <a class="reference external" href="reference-Core.html#resume()">torrent_handle::resume()</a> request. It is
generated when a torrent goes from a paused state to an active state.</p>
<pre class="literal-block">
struct torrent_resumed_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::status_notification;
};
</pre>
<a name="torrent_checked_alert"></a></div>
<div class="section" id="torrent-checked-alert">
<h1>torrent_checked_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted when a torrent completes checking. i.e. when it transitions
out of the <tt class="docutils literal">checking files</tt> state into a state where it is ready to start downloading</p>
<pre class="literal-block">
struct torrent_checked_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::status_notification;
};
</pre>
<a name="url_seed_alert"></a></div>
<div class="section" id="url-seed-alert">
<h1>url_seed_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a HTTP seed name lookup fails.</p>
<pre class="literal-block">
struct url_seed_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::peer_notification | alert::error_notification;
std::string url;
std::string msg;
};
</pre>
<a name="url"></a><dl class="docutils">
<dt>url</dt>
<dd>the HTTP seed that failed</dd>
</dl>
<a name="msg"></a><dl class="docutils">
<dt>msg</dt>
<dd>the error message, potentially from the server</dd>
</dl>
<a name="file_error_alert"></a></div>
<div class="section" id="file-error-alert">
<h1>file_error_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>If the storage fails to read or write files that it needs access to, this <a class="reference external" href="reference-Alerts.html#alert">alert</a> is
generated and the torrent is paused.</p>
<pre class="literal-block">
struct file_error_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
| alert::storage_notification;
std::string file;
error_code error;
};
</pre>
<a name="file"></a><dl class="docutils">
<dt>file</dt>
<dd>the path to the file that was accessed when the error occurred.</dd>
</dl>
<a name="error"></a><dl class="docutils">
<dt>error</dt>
<dd>the error code describing the error.</dd>
</dl>
<a name="metadata_failed_alert"></a></div>
<div class="section" id="metadata-failed-alert">
<h1>metadata_failed_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> 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.</p>
<pre class="literal-block">
struct metadata_failed_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::error_notification;
error_code error;
};
</pre>
<a name="error"></a><dl class="docutils">
<dt>error</dt>
<dd>the error that occurred</dd>
</dl>
<a name="metadata_received_alert"></a></div>
<div class="section" id="metadata-received-alert">
<h1>metadata_received_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> 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).</p>
<p>There are no additional data members in this <a class="reference external" href="reference-Alerts.html#alert">alert</a>.</p>
<p>Typically, when receiving this <a class="reference external" href="reference-Alerts.html#alert">alert</a>, you would want to save the torrent file in order
to load it back up again when the <a class="reference external" href="reference-Session.html#session">session</a> is restarted. Here's an example snippet of
code to do that:</p>
<pre class="literal-block">
torrent_handle h = alert-&gt;handle();
if (h.is_valid()) {
boost::intrusive_ptr&lt;torrent_info const&gt; ti = h.torrent_file();
create_torrent ct(*ti);
entry te = ct.generate();
std::vector&lt;char&gt; buffer;
bencode(std::back_inserter(buffer), te);
FILE* f = fopen((to_hex(ti-&gt;info_hash().to_string()) + &quot;.torrent&quot;).c_str(), &quot;wb+&quot;);
if (f) {
fwrite(&amp;buffer[0], 1, buffer.size(), f);
fclose(f);
}
}
</pre>
<pre class="literal-block">
struct metadata_received_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::status_notification;
};
</pre>
<a name="udp_error_alert"></a></div>
<div class="section" id="udp-error-alert">
<h1>udp_error_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted when there is an error on the UDP socket. The
UDP socket is used for all uTP, DHT and UDP tracker traffic. It's
global to the <a class="reference external" href="reference-Session.html#session">session</a>.</p>
<pre class="literal-block">
struct udp_error_alert: alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::error_notification;
udp::endpoint endpoint;
error_code error;
};
</pre>
<a name="endpoint"></a><dl class="docutils">
<dt>endpoint</dt>
<dd>the source address associated with the error (if any)</dd>
</dl>
<a name="error"></a><dl class="docutils">
<dt>error</dt>
<dd>the error code describing the error</dd>
</dl>
<a name="external_ip_alert"></a></div>
<div class="section" id="external-ip-alert">
<h1>external_ip_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>Whenever libtorrent learns about the machines external IP, this <a class="reference external" href="reference-Alerts.html#alert">alert</a> 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 <tt class="docutils literal">external_address</tt> member.</p>
<pre class="literal-block">
struct external_ip_alert: alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::status_notification;
address external_address;
};
</pre>
<a name="external_address"></a><dl class="docutils">
<dt>external_address</dt>
<dd>the IP address that is believed to be our external IP</dd>
</dl>
<a name="listen_failed_alert"></a></div>
<div class="section" id="listen-failed-alert">
<h1>listen_failed_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when none of the ports, given in the port range, to
<a class="reference external" href="reference-Session.html#session">session</a> can be opened for listening. The <tt class="docutils literal">endpoint</tt> member is the
interface and port that failed, <tt class="docutils literal">error</tt> is the error code describing
the failure.</p>
<p>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 <a class="reference external" href="reference-Alerts.html#listen_failed_alert">listen_failed_alert</a> with port 0 even if you didn't ask to
listen on it.</p>
<pre class="literal-block">
struct listen_failed_alert: alert
{
virtual bool <strong>discardable</strong> () const;
virtual std::string <strong>message</strong> () const;
enum socket_type_t
{
tcp,
tcp_ssl,
udp,
i2p,
socks5,
};
enum op_t
{
parse_addr,
open,
bind,
listen,
get_peer_name,
accept,
};
const static int static_category = alert::status_notification | alert::error_notification;
tcp::endpoint endpoint;
error_code error;
int operation;
socket_type_t sock_type;
};
</pre>
<a name="socket_type_t"></a><div class="section" id="enum-socket-type-t">
<h2>enum socket_type_t</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="31%" />
<col width="24%" />
<col width="45%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">value</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>tcp</td>
<td>0</td>
<td>&nbsp;</td>
</tr>
<tr><td>tcp_ssl</td>
<td>1</td>
<td>&nbsp;</td>
</tr>
<tr><td>udp</td>
<td>2</td>
<td>&nbsp;</td>
</tr>
<tr><td>i2p</td>
<td>3</td>
<td>&nbsp;</td>
</tr>
<tr><td>socks5</td>
<td>4</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<a name="op_t"></a></div>
<div class="section" id="enum-op-t">
<h2>enum op_t</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="43%" />
<col width="20%" />
<col width="37%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">value</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>parse_addr</td>
<td>0</td>
<td>&nbsp;</td>
</tr>
<tr><td>open</td>
<td>1</td>
<td>&nbsp;</td>
</tr>
<tr><td>bind</td>
<td>2</td>
<td>&nbsp;</td>
</tr>
<tr><td>listen</td>
<td>3</td>
<td>&nbsp;</td>
</tr>
<tr><td>get_peer_name</td>
<td>4</td>
<td>&nbsp;</td>
</tr>
<tr><td>accept</td>
<td>5</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<a name="endpoint"></a><dl class="docutils">
<dt>endpoint</dt>
<dd>the endpoint libtorrent attempted to listen on</dd>
</dl>
<a name="error"></a><dl class="docutils">
<dt>error</dt>
<dd>the error the system returned</dd>
</dl>
<a name="operation"></a><dl class="docutils">
<dt>operation</dt>
<dd>the specific low level operation that failed. See <a class="reference external" href="reference-Alerts.html#op_t">op_t</a>.</dd>
</dl>
<a name="sock_type"></a><dl class="docutils">
<dt>sock_type</dt>
<dd>the type of listen socket this <a class="reference external" href="reference-Alerts.html#alert">alert</a> refers to.</dd>
</dl>
<a name="listen_succeeded_alert"></a></div>
</div>
<div class="section" id="listen-succeeded-alert">
<h1>listen_succeeded_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted when the listen port succeeds to be opened on a
particular interface. <tt class="docutils literal">endpoint</tt> is the endpoint that successfully
was opened for listening.</p>
<pre class="literal-block">
struct listen_succeeded_alert: alert
{
virtual bool <strong>discardable</strong> () const;
virtual std::string <strong>message</strong> () const;
enum socket_type_t
{
tcp,
tcp_ssl,
udp,
};
const static int static_category = alert::status_notification;
tcp::endpoint endpoint;
socket_type_t sock_type;
};
</pre>
<a name="socket_type_t"></a><div class="section" id="id163">
<h2>enum socket_type_t</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="31%" />
<col width="24%" />
<col width="45%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">value</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>tcp</td>
<td>0</td>
<td>&nbsp;</td>
</tr>
<tr><td>tcp_ssl</td>
<td>1</td>
<td>&nbsp;</td>
</tr>
<tr><td>udp</td>
<td>2</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<a name="endpoint"></a><dl class="docutils">
<dt>endpoint</dt>
<dd>the endpoint libtorrent ended up listening on. The address
refers to the local interface and the port is the listen port.</dd>
</dl>
<a name="sock_type"></a><dl class="docutils">
<dt>sock_type</dt>
<dd>the type of listen socket this <a class="reference external" href="reference-Alerts.html#alert">alert</a> refers to.</dd>
</dl>
<a name="portmap_error_alert"></a></div>
</div>
<div class="section" id="portmap-error-alert">
<h1>portmap_error_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> 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 <a class="reference external" href="reference-Alerts.html#alert">alert</a> 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.</p>
<pre class="literal-block">
struct portmap_error_alert: alert
{
virtual std::string <strong>message</strong> () const;
| alert::error_notification;
int mapping;
int map_type;
error_code error;
};
</pre>
<a name="mapping"></a><dl class="docutils">
<dt>mapping</dt>
<dd>refers to the mapping index of the port map that failed, i.e.
the index returned from add_mapping().</dd>
</dl>
<a name="map_type"></a><dl class="docutils">
<dt>map_type</dt>
<dd>is 0 for NAT-PMP and 1 for UPnP.</dd>
</dl>
<a name="error"></a><dl class="docutils">
<dt>error</dt>
<dd>tells you what failed.</dd>
</dl>
<a name="portmap_alert"></a></div>
<div class="section" id="portmap-alert">
<h1>portmap_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> 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.</p>
<pre class="literal-block">
struct portmap_alert: alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::port_mapping_notification;
int mapping;
int external_port;
int map_type;
};
</pre>
<a name="mapping"></a><dl class="docutils">
<dt>mapping</dt>
<dd>refers to the mapping index of the port map that failed, i.e.
the index returned from add_mapping().</dd>
</dl>
<a name="external_port"></a><dl class="docutils">
<dt>external_port</dt>
<dd>the external port allocated for the mapping.</dd>
</dl>
<a name="map_type"></a><dl class="docutils">
<dt>map_type</dt>
<dd>0 for NAT-PMP and 1 for UPnP.</dd>
</dl>
<a name="portmap_log_alert"></a></div>
<div class="section" id="portmap-log-alert">
<h1>portmap_log_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> 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.</p>
<pre class="literal-block">
struct portmap_log_alert: alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::port_mapping_notification;
int map_type;
std::string msg;
};
</pre>
<a name="fastresume_rejected_alert"></a></div>
<div class="section" id="fastresume-rejected-alert">
<h1>fastresume_rejected_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a fastresume file has been passed to <a class="reference external" href="reference-Session.html#add_torrent()">add_torrent()</a> but the
files on disk did not match the fastresume file. The error_code explains the reason why the
resume file was rejected.</p>
<pre class="literal-block">
struct fastresume_rejected_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
| alert::error_notification;
error_code error;
};
</pre>
<a name="peer_blocked_alert"></a></div>
<div class="section" id="peer-blocked-alert">
<h1>peer_blocked_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> 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:</p>
<ul class="simple">
<li>the IP filter</li>
<li>i2p mixed mode restrictions (a normal peer is not allowed on an i2p swarm)</li>
<li>the port filter</li>
<li>the peer has a low port and <tt class="docutils literal">no_connect_privileged_ports</tt> is enabled</li>
<li>the protocol of the peer is blocked (uTP/TCP blocking)</li>
</ul>
<pre class="literal-block">
struct peer_blocked_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
enum reason_t
{
ip_filter,
port_filter,
i2p_mixed,
privileged_ports,
utp_disabled,
tcp_disabled,
};
const static int static_category = alert::ip_block_notification;
address ip;
int reason;
};
</pre>
<a name="reason_t"></a><div class="section" id="enum-reason-t">
<h2>enum reason_t</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="47%" />
<col width="18%" />
<col width="34%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">value</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>ip_filter</td>
<td>0</td>
<td>&nbsp;</td>
</tr>
<tr><td>port_filter</td>
<td>1</td>
<td>&nbsp;</td>
</tr>
<tr><td>i2p_mixed</td>
<td>2</td>
<td>&nbsp;</td>
</tr>
<tr><td>privileged_ports</td>
<td>3</td>
<td>&nbsp;</td>
</tr>
<tr><td>utp_disabled</td>
<td>4</td>
<td>&nbsp;</td>
</tr>
<tr><td>tcp_disabled</td>
<td>5</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<a name="ip"></a><dl class="docutils">
<dt>ip</dt>
<dd>the address that was blocked.</dd>
</dl>
<a name="dht_announce_alert"></a></div>
</div>
<div class="section" id="dht-announce-alert">
<h1>dht_announce_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a DHT node announces to an info-hash on our
DHT node. It belongs to the <tt class="docutils literal">dht_notification</tt> category.</p>
<pre class="literal-block">
struct dht_announce_alert: alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::dht_notification;
address ip;
int port;
sha1_hash info_hash;
};
</pre>
<a name="dht_get_peers_alert"></a></div>
<div class="section" id="dht-get-peers-alert">
<h1>dht_get_peers_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when a DHT node sends a <tt class="docutils literal">get_peers</tt> message to
our DHT node. It belongs to the <tt class="docutils literal">dht_notification</tt> category.</p>
<pre class="literal-block">
struct dht_get_peers_alert: alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::dht_notification;
sha1_hash info_hash;
};
</pre>
<a name="stats_alert"></a></div>
<div class="section" id="stats-alert">
<h1>stats_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> 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.</p>
<pre class="literal-block">
struct stats_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
enum stats_channel
{
upload_payload,
upload_protocol,
download_payload,
download_protocol,
upload_ip_protocol,
upload_dht_protocol,
upload_tracker_protocol,
download_ip_protocol,
download_dht_protocol,
download_tracker_protocol,
num_channels,
};
const static int static_category = alert::stats_notification;
int transferred[num_channels];
int interval;
};
</pre>
<a name="stats_channel"></a><div class="section" id="enum-stats-channel">
<h2>enum stats_channel</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="57%" />
<col width="15%" />
<col width="28%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">value</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>upload_payload</td>
<td>0</td>
<td>&nbsp;</td>
</tr>
<tr><td>upload_protocol</td>
<td>1</td>
<td>&nbsp;</td>
</tr>
<tr><td>download_payload</td>
<td>2</td>
<td>&nbsp;</td>
</tr>
<tr><td>download_protocol</td>
<td>3</td>
<td>&nbsp;</td>
</tr>
<tr><td>upload_ip_protocol</td>
<td>4</td>
<td>&nbsp;</td>
</tr>
<tr><td>upload_dht_protocol</td>
<td>5</td>
<td>&nbsp;</td>
</tr>
<tr><td>upload_tracker_protocol</td>
<td>6</td>
<td>&nbsp;</td>
</tr>
<tr><td>download_ip_protocol</td>
<td>7</td>
<td>&nbsp;</td>
</tr>
<tr><td>download_dht_protocol</td>
<td>8</td>
<td>&nbsp;</td>
</tr>
<tr><td>download_tracker_protocol</td>
<td>9</td>
<td>&nbsp;</td>
</tr>
<tr><td>num_channels</td>
<td>10</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<a name="transferred[num_channels]"></a><dl class="docutils">
<dt>transferred[num_channels]</dt>
<dd>an array of samples. The enum describes what each sample is a
measurement of. All of these are raw, and not smoothing is performed.</dd>
</dl>
<a name="interval"></a><dl class="docutils">
<dt>interval</dt>
<dd>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.</dd>
</dl>
<a name="cache_flushed_alert"></a></div>
</div>
<div class="section" id="cache-flushed-alert">
<h1>cache_flushed_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted when the disk cache has been flushed for a specific
torrent as a result of a call to <a class="reference external" href="reference-Core.html#flush_cache()">torrent_handle::flush_cache()</a>. This
<a class="reference external" href="reference-Alerts.html#alert">alert</a> belongs to the <tt class="docutils literal">storage_notification</tt> category, which must be
enabled to let this <a class="reference external" href="reference-Alerts.html#alert">alert</a> through. The <a class="reference external" href="reference-Alerts.html#alert">alert</a> is also posted when removing
a torrent from the <a class="reference external" href="reference-Session.html#session">session</a>, once the outstanding cache flush is complete
and the torrent does no longer have any files open.</p>
<pre class="literal-block">
struct cache_flushed_alert: torrent_alert
{
const static int static_category = alert::storage_notification;
};
</pre>
<a name="anonymous_mode_alert"></a></div>
<div class="section" id="anonymous-mode-alert">
<h1>anonymous_mode_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> 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.</p>
<pre class="literal-block">
struct anonymous_mode_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
enum kind_t
{
tracker_not_anonymous,
};
const static int static_category = alert::error_notification;
int kind;
std::string str;
};
</pre>
<a name="kind_t"></a><div class="section" id="enum-kind-t">
<h2>enum kind_t</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="23%" />
<col width="7%" />
<col width="70%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">value</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>tracker_not_anonymous</td>
<td>0</td>
<td>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 <tt class="docutils literal">str</tt> member.</td>
</tr>
</tbody>
</table>
<a name="kind"></a>
<a name="str"></a><dl class="docutils">
<dt>kind str</dt>
<dd>specifies what error this is, see <a class="reference external" href="reference-Alerts.html#kind_t">kind_t</a>.</dd>
</dl>
<a name="lsd_peer_alert"></a></div>
</div>
<div class="section" id="lsd-peer-alert">
<h1>lsd_peer_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is generated when we receive a local service discovery message
from a peer for a torrent we're currently participating in.</p>
<pre class="literal-block">
struct lsd_peer_alert: peer_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::peer_notification;
};
</pre>
<a name="trackerid_alert"></a></div>
<div class="section" id="trackerid-alert">
<h1>trackerid_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted whenever a tracker responds with a <tt class="docutils literal">trackerid</tt>.
The tracker ID is like a cookie. The libtorrent will store the tracker ID
for this tracker and repeat it in subsequent announces.</p>
<pre class="literal-block">
struct trackerid_alert: tracker_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::status_notification;
std::string trackerid;
};
</pre>
<a name="trackerid"></a><dl class="docutils">
<dt>trackerid</dt>
<dd>The tracker ID returned by the tracker</dd>
</dl>
<a name="dht_bootstrap_alert"></a></div>
<div class="section" id="dht-bootstrap-alert">
<h1>dht_bootstrap_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted when the initial DHT bootstrap is done.</p>
<pre class="literal-block">
struct dht_bootstrap_alert: alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::dht_notification;
};
</pre>
<a name="rss_alert"></a></div>
<div class="section" id="rss-alert">
<h1>rss_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted on RSS feed events such as start of RSS feed updates,
successful completed updates and errors during updates.</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is only posted if the <tt class="docutils literal">rss_notifications</tt> category is enabled
in the alert_mask.</p>
<pre class="literal-block">
struct rss_alert: alert
{
virtual std::string <strong>message</strong> () const;
enum state_t
{
state_updating,
state_updated,
state_error,
};
const static int static_category = alert::rss_notification;
feed_handle handle;
std::string url;
int state;
error_code error;
};
</pre>
<a name="state_t"></a><div class="section" id="enum-state-t">
<h2>enum state_t</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="17%" />
<col width="8%" />
<col width="75%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">value</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>state_updating</td>
<td>0</td>
<td>An update of this feed was just initiated, it will either succeed
or fail soon.</td>
</tr>
<tr><td>state_updated</td>
<td>1</td>
<td>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 <tt class="docutils literal">items</tt> vector.</td>
</tr>
<tr><td>state_error</td>
<td>2</td>
<td>An error just occurred. See the <tt class="docutils literal">error</tt> field for information on
what went wrong.</td>
</tr>
</tbody>
</table>
<a name="handle"></a><dl class="docutils">
<dt>handle</dt>
<dd>the handle to the feed which generated this <a class="reference external" href="reference-Alerts.html#alert">alert</a>.</dd>
</dl>
<a name="url"></a><dl class="docutils">
<dt>url</dt>
<dd>a short cut to access the url of the feed, without
having to call feed_handle::get_settings().</dd>
</dl>
<a name="state"></a><dl class="docutils">
<dt>state</dt>
<dd>one of the values from <a class="reference external" href="reference-Alerts.html#state_t">rss_alert::state_t</a>.</dd>
</dl>
<a name="error"></a><dl class="docutils">
<dt>error</dt>
<dd>an error code used for when an error occurs on the feed.</dd>
</dl>
<a name="torrent_error_alert"></a></div>
</div>
<div class="section" id="torrent-error-alert">
<h1>torrent_error_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This is posted whenever a torrent is transitioned into the error state.</p>
<pre class="literal-block">
struct torrent_error_alert: torrent_alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::error_notification | alert::status_notification;
error_code error;
};
</pre>
<a name="error"></a><dl class="docutils">
<dt>error</dt>
<dd>specifies which error the torrent encountered.</dd>
</dl>
<a name="torrent_need_cert_alert"></a></div>
<div class="section" id="torrent-need-cert-alert">
<h1>torrent_need_cert_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This is always posted for SSL torrents. This is a reminder to the client that
the torrent won't work unless <a class="reference external" href="reference-Core.html#set_ssl_certificate()">torrent_handle::set_ssl_certificate()</a> is called with
a valid certificate. Valid certificates MUST be signed by the SSL certificate
in the .torrent file.</p>
<pre class="literal-block">
struct torrent_need_cert_alert: torrent_alert
{
virtual bool <strong>discardable</strong> () const;
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::status_notification;
error_code error;
};
</pre>
<a name="incoming_connection_alert"></a></div>
<div class="section" id="incoming-connection-alert">
<h1>incoming_connection_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>The incoming connection <a class="reference external" href="reference-Alerts.html#alert">alert</a> 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.</p>
<pre class="literal-block">
struct incoming_connection_alert: alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::peer_notification;
int socket_type;
tcp::endpoint ip;
};
</pre>
<a name="socket_type"></a><dl class="docutils">
<dt>socket_type</dt>
<dd><p class="first">tells you what kind of socket the connection was accepted
as:</p>
<ol class="last arabic simple" start="0">
<li>none (no socket instantiated)</li>
<li>TCP</li>
<li>Socks5</li>
<li>HTTP</li>
<li>uTP</li>
<li>i2p</li>
<li>SSL/TCP</li>
<li>SSL/Socks5</li>
<li>HTTPS (SSL/HTTP)</li>
<li>SSL/uTP</li>
</ol>
</dd>
</dl>
<a name="ip"></a><dl class="docutils">
<dt>ip</dt>
<dd>is the IP address and port the connection came from.</dd>
</dl>
<a name="add_torrent_alert"></a></div>
<div class="section" id="add-torrent-alert">
<h1>add_torrent_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> 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' <tt class="docutils literal">handle</tt> member. If adding
the torrent failed, <tt class="docutils literal">error</tt> contains the error code.</p>
<pre class="literal-block">
struct add_torrent_alert : torrent_alert
{
virtual bool <strong>discardable</strong> () const;
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::status_notification;
add_torrent_params params;
error_code error;
};
</pre>
<a name="params"></a><dl class="docutils">
<dt>params</dt>
<dd>a copy of the parameters used when adding the torrent, it can be used
to identify which invocation to <tt class="docutils literal">async_add_torrent()</tt> caused this <a class="reference external" href="reference-Alerts.html#alert">alert</a>.</dd>
</dl>
<a name="error"></a><dl class="docutils">
<dt>error</dt>
<dd>set to the error, if one occurred while adding the torrent.</dd>
</dl>
<a name="state_update_alert"></a></div>
<div class="section" id="state-update-alert">
<h1>state_update_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is only posted when requested by the user, by calling <a class="reference external" href="reference-Session.html#post_torrent_updates()">session::post_torrent_updates()</a>
on the <a class="reference external" href="reference-Session.html#session">session</a>. It contains the torrent status of all torrents that changed
since last time this message was posted. Its category is <tt class="docutils literal">status_notification</tt>, but
it's not subject to filtering, since it's only manually posted anyway.</p>
<pre class="literal-block">
struct state_update_alert : alert
{
virtual bool <strong>discardable</strong> () const;
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::status_notification;
std::vector&lt;torrent_status&gt; status;
};
</pre>
<a name="status"></a><dl class="docutils">
<dt>status</dt>
<dd>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 <tt class="docutils literal">handle</tt> member. The receiving end is suggested to have all torrents sorted
by the <a class="reference external" href="reference-Core.html#torrent_handle">torrent_handle</a> or hashed by it, for efficient updates.</dd>
</dl>
<a name="torrent_update_alert"></a></div>
<div class="section" id="torrent-update-alert">
<h1>torrent_update_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>When a torrent changes its info-hash, this <a class="reference external" href="reference-Alerts.html#alert">alert</a> 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.</p>
<p>Once this download completes, the <tt class="docutils literal">torrent_update_alert</tt> is posted to notify the client
of the info-hash changing.</p>
<pre class="literal-block">
struct torrent_update_alert : torrent_alert
{
virtual bool <strong>discardable</strong> () const;
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::status_notification;
sha1_hash old_ih;
sha1_hash new_ih;
};
</pre>
<a name="old_ih"></a>
<a name="new_ih"></a><dl class="docutils">
<dt>old_ih new_ih</dt>
<dd><tt class="docutils literal">old_ih</tt> and <tt class="docutils literal">new_ih</tt> are the previous and new info-hash for the torrent, respectively.</dd>
</dl>
<a name="rss_item_alert"></a></div>
<div class="section" id="rss-item-alert">
<h1>rss_item_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>This <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted every time a new RSS item (i.e. torrent) is received
from an RSS feed.</p>
<p>It is only posted if the <tt class="docutils literal">rss_notifications</tt> category is enabled in the
alert_mask.</p>
<pre class="literal-block">
struct rss_item_alert : alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::rss_notification;
feed_handle handle;
feed_item item;
};
</pre>
<a name="dht_error_alert"></a></div>
<div class="section" id="dht-error-alert">
<h1>dht_error_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>posted when something fails in the DHT. This is not necessarily a fatal
error, but it could prevent proper operation</p>
<pre class="literal-block">
struct dht_error_alert: alert
{
virtual std::string <strong>message</strong> () const;
enum op_t
{
unknown,
hostname_lookup,
};
| alert::dht_notification;
error_code error;
op_t operation;
};
</pre>
<a name="op_t"></a><div class="section" id="id227">
<h2>enum op_t</h2>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<table border="1" class="docutils">
<colgroup>
<col width="46%" />
<col width="19%" />
<col width="35%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">value</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>unknown</td>
<td>0</td>
<td>&nbsp;</td>
</tr>
<tr><td>hostname_lookup</td>
<td>1</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<a name="error"></a><dl class="docutils">
<dt>error</dt>
<dd>the error code</dd>
</dl>
<a name="operation"></a><dl class="docutils">
<dt>operation</dt>
<dd>the operation that failed</dd>
</dl>
<a name="dht_immutable_item_alert"></a></div>
</div>
<div class="section" id="dht-immutable-item-alert">
<h1>dht_immutable_item_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>this <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted as a response to a call to session::get_item(),
specifically the overload for looking up immutable items in the DHT.</p>
<pre class="literal-block">
struct dht_immutable_item_alert: alert
{
virtual bool <strong>discardable</strong> () const;
<strong>dht_immutable_item_alert</strong> (sha1_hash const&amp; t, entry const&amp; i);
virtual std::string <strong>message</strong> () const;
| alert::dht_notification;
sha1_hash target;
entry item;
};
</pre>
<a name="target"></a><dl class="docutils">
<dt>target</dt>
<dd>the target hash of the immutable item. This must
match the sha-1 hash of the bencoded form of <tt class="docutils literal">item</tt>.</dd>
</dl>
<a name="item"></a><dl class="docutils">
<dt>item</dt>
<dd>the data for this item</dd>
</dl>
<a name="dht_mutable_item_alert"></a></div>
<div class="section" id="dht-mutable-item-alert">
<h1>dht_mutable_item_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>this <a class="reference external" href="reference-Alerts.html#alert">alert</a> is posted as a response to a call to session::get_item(),
specifically the overload for looking up mutable items in the DHT.</p>
<pre class="literal-block">
struct dht_mutable_item_alert: alert
{
<strong>dht_mutable_item_alert</strong> (boost::array&lt;char, 32&gt; k
, boost::array&lt;char, 64&gt; sig
, boost::uint64_t sequence
, std::string const&amp; s
, entry const&amp; i);
virtual bool <strong>discardable</strong> () const;
virtual std::string <strong>message</strong> () const;
| alert::dht_notification;
boost::array&lt;char, 32&gt; key;
boost::array&lt;char, 64&gt; signature;
boost::uint64_t seq;
std::string salt;
entry item;
};
</pre>
<a name="key"></a><dl class="docutils">
<dt>key</dt>
<dd>the public key that was looked up</dd>
</dl>
<a name="signature"></a><dl class="docutils">
<dt>signature</dt>
<dd>the signature of the data. This is not the signature of the
plain encoded form of the item, but it includes the sequence number
and possibly the hash as well. See the dht_store document for more
information. This is primarily useful for echoing back in a store
request.</dd>
</dl>
<a name="seq"></a><dl class="docutils">
<dt>seq</dt>
<dd>the sequence number of this item</dd>
</dl>
<a name="salt"></a><dl class="docutils">
<dt>salt</dt>
<dd>the salf, if any, used to lookup and store this item. If no
salt was used, this is an empty string</dd>
</dl>
<a name="item"></a><dl class="docutils">
<dt>item</dt>
<dd>the data for this item</dd>
</dl>
<a name="dht_put_alert"></a></div>
<div class="section" id="dht-put-alert">
<h1>dht_put_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>this is posted when a DHT put operation completes. This is useful if the
client is waiting for a put to complete before shutting down for instance.</p>
<pre class="literal-block">
struct dht_put_alert: alert
{
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::dht_notification;
sha1_hash target;
boost::array&lt;char, 32&gt; public_key;
boost::array&lt;char, 64&gt; signature;
std::string salt;
boost::uint64_t seq;
};
</pre>
<a name="target"></a><dl class="docutils">
<dt>target</dt>
<dd>the target hash the item was stored under if this was an <em>immutable</em>
item.</dd>
</dl>
<a name="public_key"></a>
<a name="signature"></a>
<a name="salt"></a>
<a name="seq"></a><dl class="docutils">
<dt>public_key signature salt seq</dt>
<dd>if a mutable item was stored, these are the public key, signature,
salt and sequence number the item was stored under.</dd>
</dl>
<a name="i2p_alert"></a></div>
<div class="section" id="i2p-alert">
<h1>i2p_alert</h1>
<p>Declared in &quot;<a class="reference external" href="../include/libtorrent/alert_types.hpp">libtorrent/alert_types.hpp</a>&quot;</p>
<p>this <a class="reference external" href="reference-Alerts.html#alert">alert</a> is used to report errors in the i2p SAM connection</p>
<pre class="literal-block">
struct i2p_alert : alert
{
<strong>i2p_alert</strong> (error_code const&amp; ec);
virtual std::string <strong>message</strong> () const;
const static int static_category = alert::error_notification;
error_code error;
};
</pre>
<a name="error"></a><dl class="docutils">
<dt>error</dt>
<dd>the error that occurred in the i2p SAM connection</dd>
</dl>
</div>
</div>
<div id="footer">
<span>Copyright &copy; 2005-2013 Rasterbar Software.</span>
</div>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-1599045-1";
urchinTracker();
</script>
</div>
</body>
</html>