ping — XMPP Ping (XEP-0199)

XMPP Ping is a ping on the XMPP protocol level. It can be used to detect connection liveness (although aioxmpp.stream.StanzaStream and thus aioxmpp.Client does that for you) and connectivity/availablility of remote domains.

Service

class aioxmpp.PingService[source]

Service implementing XMPP Ping (XEP-0199).

This service implements the response to XMPP Pings and provides a method to send pings.

coroutine ping(peer)[source]

Wrapper around aioxmpp.ping.ping().

When to use this wrapper vs. the global function: Using this method has the side effect that the application will start to respond to XEP-0199 pings. While this is not a security issue per se (as responding to XEP-0199 pings only changes the format of the reply, not the fact that a reply is sent from the client), it may not be desirable under all circumstances.

So especially when developing a Service which does not reqiure that the application replies to pings (for example, when implementing a stream or group chat aliveness check), it is preferrable to use the global function.

When implementing an application where it is desirable to reply to pings, using this wrapper is fine.

In general, aioxmpp services should avoid depending on this service.

(The decision essentially boils down to “summon this service or not?”, and it is not a decision aioxmpp should make for the application unless necessary for compliance.)

Changed in version 0.11: Converted to a shim wrapper.

coroutine aioxmpp.ping.ping(client, peer)[source]

Ping a peer.

Parameters:peer (aioxmpp.JID) – The peer to ping.
Raises:aioxmpp.errors.XMPPError – as received

Send a XEP-0199 ping IQ to peer and wait for the reply.

This is a low-level version of aioxmpp.PingService.ping().

When to use this function vs. the service method: See aioxmpp.PingService.ping().

Note

If the peer does not support XEP-0199, they will respond with a cancel service-unavailable error. However, some implementations return a cancel feature-not-implemented error instead. Callers should be prepared for the aioxmpp.XMPPCancelError exceptions in those cases.

Changed in version 0.11: Extracted this helper from aioxmpp.PingService.

XSOs

Sometimes it is useful to send a ping manually instead of relying on the Service. For this, the Ping IQ payload can be used.

class aioxmpp.ping.Ping[source]

Simple XSO to represent an XMPP ping.

It takes no arguments and has no attributes or children.