pub enum Alert {
Show 34 variants
NotImplemented,
UdpError(UdpErrorAlert),
ExternalIp(ExternalIpAlert),
ListenFailed(ListenFailedAlert),
ListenSucceeded(ListenSucceededAlert),
PortmapError(PortmapErrorAlert),
Portmap(PortmapAlert),
PortmapLog(PortmapLogAlert),
DhtAnnounce(DhtAnnounceAlert),
DhtGetPeers(DhtGetPeersAlert),
DhtBootstrap(DhtBootstrapAlert),
IncomingConnection(IncomingConnectionAlert),
StateUpdate(StateUpdateAlert),
SessionStats(SessionStatsAlert),
DhtError(DhtErrorAlert),
DhtImmutableItem(DhtImmutableItemAlert),
DhtMutableItem(DhtMutableItemAlert),
DhtPut(DhtPutAlert),
I2p(I2pAlert),
DhtOutgoingGetPeers(DhtOutgoingGetPeersAlert),
Log(LogAlert),
LsdError(LsdErrorAlert),
DhtStats(DhtStatsAlert),
DhtLog(DhtLogAlert),
DhtPkt(DhtPktAlert),
DhtGetPeersReply(DhtGetPeersReplyAlert),
DhtDirectResponse(DhtDirectResponseAlert),
SessionError(SessionErrorAlert),
DhtLiveNodes(DhtLiveNodesAlert),
SessionStatsHeader(SessionStatsHeaderAlert),
DhtSampleInfohashes(DhtSampleInfohashesAlert),
AlertsDropped(AlertsDroppedAlert),
Socks5(Socks5Alert),
TorrentAlert(TorrentAlert),
}Expand description
The [LtSession::pop_alerts()] function on session is the main interface for retrieving alerts
(warnings, messages and errors from libtorrent).
If no alerts have been posted by libtorrent [LtSession::pop_alerts()] will return an empty list.
By default, only errors are reported. [SettingsPack::set_alert_mask()] can be used to specify
which kinds of events should be reported. The alert mask is a combination of the AlertCategory flags.
Every alert belongs to one or more category. There is a cost associated with posting alerts. Only alerts that belong to an enabled category are posted. Setting the alert bitmask to 0 will disable all alerts (except those that are non-discardable). Alerts that are responses to API calls such as save_resume_data() and post_session_stats() are //TODO function reference non-discardable and will be posted even if their category is disabled.
There are other alert base classes that some alerts derive from, all the alerts that are
generated for a specific torrent are derived from TorrentAlert,
and tracker events derive from TrackerAlert.
Alerts returned by [LtSession::pop_alerts()] are only valid until the next call to [LtSession::pop_alerts()].
You may not copy an alert object to access it after the next call to [LtSession::pop_alerts()].
Internal members of alerts also become invalid once [LtSession::pop_alerts()] is called again.
Variants§
NotImplemented
UdpError(UdpErrorAlert)
This alert is posted when there is an error on a UDP socket. The UDP sockets are used for all uTP, DHT and UDP tracker traffic. They are global to the session.
§Alert Category
§Alert Priority
ExternalIp(ExternalIpAlert)
Whenever libtorrent learns about the machines external IP, this alert is
generated. The external IP address can be acquired from the tracker (if it
supports that) or from peers that supports the extension protocol.
The address can be accessed through the external_address member.
§Alert Category
§Alert Priority
ListenFailed(ListenFailedAlert)
This alert is generated when none of the ports, given in the port range, to
session can be opened for listening. The listen_interface member is the
interface that failed, error is the error code describing the failure.
In the case an endpoint was created before generating the alert, it is
represented by address and port. The combinations of socket type
and operation in which such address and port are not valid are:
accept - i2p
accept - socks5
enum_if - tcp
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 Alert::ListenFailed with port 0 even if you didn’t ask to
listen on it.
§Alert Category
AlertCategory::Status | AlertCategory::Error
§Alert Priority
ListenSucceeded(ListenSucceededAlert)
This alert is posted when the listen port succeeds to be opened on a
particular interface. address and port is the endpoint that
successfully was opened for listening.
§Alert Category
§Alert Priority
PortmapError(PortmapErrorAlert)
This alert is generated when a NAT router was successfully found but some part of the port mapping request failed. It contains a text message that may help the user figure out what is wrong. This alert is not generated in case it appears the client is not running on a NAT:ed network or if it appears there is no NAT router that can be remote controlled to add port mappings.
§Alert Category
AlertCategory::PortMapping | AlertCategory::Error
§Alert Priority
Portmap(PortmapAlert)
This alert is generated when a NAT router was successfully found and a port was successfully mapped on it. On a NAT:ed network with a NAT-PMP capable router, this is typically generated once when mapping the TCP port and, if DHT is enabled, when the UDP port is mapped.
§Alert Category
§Alert Priority
PortmapLog(PortmapLogAlert)
This alert is generated to log informational events related to either UPnP or NAT-PMP. They contain a log line and the type (0 = NAT-PMP and 1 = UPnP). Displaying these messages to an end user is only useful for debugging the UPnP or NAT-PMP implementation. This alert is only posted if the alert_category::port_mapping_log flag is enabled in the alert mask.
§Alert Category
§Alert Priority
DhtAnnounce(DhtAnnounceAlert)
This alert is generated when a DHT node announces to an info-hash on our DHT node.
§Alert Category
§Alert Priority
DhtGetPeers(DhtGetPeersAlert)
This alert is generated when a DHT node sends a get_peers message to
our DHT node.
§Alert Category
§Alert Priority
DhtBootstrap(DhtBootstrapAlert)
IncomingConnection(IncomingConnectionAlert)
The incoming connection alert is posted every time we successfully accept an incoming connection, through any mean. The most straight-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 through a Socks5 or i2p listen socket, or via an SSL listen socket.
§Alert Category
§Alert Priority
[AlertPriority::Peer]
StateUpdate(StateUpdateAlert)
This alert is only posted when requested by the user, by calling [LtSession::post_torrent_updates()] on the session.
It contains the torrent status of all torrents that changed since last time this message was posted.
Its category is AlertCategory::Status, but it’s not subject to filtering, since it’s only manually posted anyway.
§Alert Category
§Alert Priority
SessionStats(SessionStatsAlert)
The Alert::SessionStats is posted when the user requests session statistics by
calling post_session_stats() on the session object. This alert does not
have a category, since it’s only posted in response to an API call. It
is not subject to the alert_mask filter.
the message() member function returns a string representation of the values that
properly match the line returned in session_stats_header_alert::message().
this specific output is parsed by tools/parse_session_stats.py if this is changed, that parser should also be changed
§Alert Category
§Alert Priority
DhtError(DhtErrorAlert)
Posted when something fails in the DHT. This is not necessarily a fatal error, but it could prevent proper operation
§Alert Category
AlertCategory::Dht AlertCategory::Error
§Alert Priority
DhtImmutableItem(DhtImmutableItemAlert)
This alert is posted as a response to a call to [LtSession::get_item()],
specifically the overload for looking up immutable items in the DHT.
§Alert Category
§Alert Priority
DhtMutableItem(DhtMutableItemAlert)
This alert is posted as a response to a call to [LtSession::get_item()],
specifically the overload for looking up mutable items in the DHT.
§Alert Category
§Alert Priority
DhtPut(DhtPutAlert)
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.
§Alert Category
§Alert Priority
I2p(I2pAlert)
DhtOutgoingGetPeers(DhtOutgoingGetPeersAlert)
Log(LogAlert)
This alert is posted by some session wide event. Its main purpose is
trouble shooting and debugging. It’s not enabled by the default alert
mask and is enabled by the AlertCategory::SessionLog bit.
Furthermore, it’s by default disabled as a build configuration.
§Alert Category
§Alert Priority
LsdError(LsdErrorAlert)
Posted if the local service discovery socket fails to start properly.
§Alert Category
§Alert Priority
DhtStats(DhtStatsAlert)
Contains current DHT state. Posted in response to [LtSession::post_dht_stats()].
§Alert Category
§Alert Priority
DhtLog(DhtLogAlert)
Debug logging of the DHT when AlertCategory::DhtLog is set in the alert
mask.
§Alert Category
§Alert Priority
DhtPkt(DhtPktAlert)
This alert is posted every time a DHT message is sent or received. It is
only posted if the AlertCategory::DhtLog alert category is
enabled. It contains a verbatim copy of the message.
§Alert Category
§Alert Priority
DhtGetPeersReply(DhtGetPeersReplyAlert)
DhtDirectResponse(DhtDirectResponseAlert)
This is posted exactly once for every call to session_handle::dht_direct_request. If the request failed, response() will return a default constructed bdecode_node.
§Alert Category
§Alert Priority
SessionError(SessionErrorAlert)
This alert is posted when the session encounters a serious error, potentially fatal
§Alert Category
§Alert Priority
DhtLiveNodes(DhtLiveNodesAlert)
Posted in response to a call to [LtSession::dht_live_nodes()]. It contains the
live nodes from the DHT routing table of one of the DHT nodes running
locally.
§Alert Category
§Alert Priority
SessionStatsHeader(SessionStatsHeaderAlert)
The session_stats_header alert is posted the first time post_session_stats() is called
the message() member function returns a string representation of the
header that properly match the stats values string returned in
session_stats_alert::message().
§Alert Category
§Alert Priority
DhtSampleInfohashes(DhtSampleInfohashesAlert)
Posted as a response to a call to [LtSession::dht_sample_infohashes()] with
the information from the DHT response message.
§Alert Category
§Alert Priority
AlertsDropped(AlertsDroppedAlert)
This alert is posted to indicate to the client that some alerts were dropped. Dropped meaning that the alert failed to be delivered to the client. The most common cause of such failure is that the internal alert queue grew too big (controlled by alert_queue_size).
§Alert Category
§Alert Priority
Socks5(Socks5Alert)
This alert is posted with SOCKS5 related errors, when a SOCKS5 proxy is configured. It’s enabled with the AlertCategory::Error alert category.
§Alert Category
§Alert Priority
TorrentAlert(TorrentAlert)
This is a base variant for alerts that are associated with a specific torrent. It contains a handle to the torrent.
Note that by the time the client receives a TorrentAlert, its handle member may be invalid.