# `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

  Service implementing XMPP Ping (XEP-0199).

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

  async ping(peer)

    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 require that the application replies to pings (for example, when implementing a stream or group chat aliveness check), it is preferable 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.

async aioxmpp.ping.ping(client, peer)

  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

  Simple XSO to represent an XMPP ping.

  It takes no arguments and has no attributes or children.