---
name: "AnyEvent::XMPP::Ext::Ping"
section: "3pm"
platform: "linux"
package: "perl-anyevent-xmpp"
version: "0.55-7"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/AnyEvent::XMPP::Ext::Ping"
---

# AnyEvent::XMPP::Ext::Ping(3pm)

Implementation of XMPP Ping XEP-0199

## NAME

AnyEvent::XMPP::Ext::Ping - Implementation of XMPP Ping XEP-0199

## SYNOPSIS

```
   use AnyEvent::XMPP::Ext::Ping;
   my $con = AnyEvent::XMPP::IM::Connection->new (...);
   $con->add_extension (my $ping = AnyEvent::XMPP::Ext::Ping->new);
   # this enables auto-timeout of a connection if it didn't answer
   # within 120 seconds to a ping with a reply
   $ping->enable_timeout ($con, 120);
   my $cl = AnyEvent::XMPP::Client->new (...);
   $cl->add_extension (my $ping = AnyEvent::XMPP::Ext::Ping->new);
   # this enables auto-timeout of newly created connections
   $ping->auto_timeout (120);
   $ping->ping ($con, 'ping_dest@server.tld', sub {
      my ($time, $error) = @_;
      if ($error) {
         # we got an error
      }
      # $time is a float (seconds) of the rtt if you got Time::HiRes
   });
```

## DESCRIPTION

This extension implements XEP-0199: XMPP Ping. It allows you to define a automatic ping timeouter that will disconnect dead connections (which didn't reply to a ping after N seconds). See also the documentation of the `"enable_timeout"` method below.

It also allows you to send pings to any XMPP entity you like and will measure the time it took if you got Time::HiRes.

## METHODS

- **new (%args)**

  Creates a new ping handle.

- **auto\_timeout ($timeout)**

  This method enables automatic connection timeout of new connections. It calls `"enable_timeout"` (see below) for every new connection that was connected and emitted a `"stream_ready"` event.

  This is useful if you want connections that have this extension automatically timeouted. In particular this is useful with modules like AnyEvent::XMPP::Client (see also SYNOPSIS above).

- **enable\_timeout ($con, $timeout)**

  This enables a periodical ping on the connection `$con`. `$timeout` must be the seconds that the ping intervals last.

  If the server which is connected via `$con` didn't respond within `$timeout` seconds the connection `$con` will be disconnected.

  Please note that there already is a basic timeout mechanism for dead TCP connections in AnyEvent::XMPP::Connection, see also the `"whitespace_ping_interval"` configuration variable for a connection there. It then will depend on TCP timeouts to disconnect the connection.

  Use `"enable_timeout"` and `"auto_timeout"` only if you really feel like you need an explicit timeout for your connections.

- **ping ($con, $dest, $cb, $timeout)**

  This method sends a ping request to `$dest` via the AnyEvent::XMPP::Connection in `$con`. If `$dest` is undefined the ping will be sent to the connected server.  `$cb` will be called when either the ping timeouts, an error occurs or the ping result was received. `$timeout` is an optional timeout for the ping request, if `$timeout` is not given the default IQ timeout for the connection is the relevant timeout.

  The first argument to `$cb` will be the seconds of the round trip time for that request (If you have Time::HiRes).  If you don't have Time::HiRes installed the first argument will be undef.

  The second argument to `$cb` will be either undef if no error occured or a AnyEvent::XMPP::Error::IQ error object.

- **ignore\_pings ($bool)**

  This method is mostly for testing, it tells this extension to ignore all ping requests and will prevent any response from being sent.

## AUTHOR

Robin Redeker, `"<elmex at ta-sa.org>"`, JID: `"<elmex at jabber.org>"`

## COPYRIGHT & LICENSE

Copyright 2007, 2008 Robin Redeker, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.