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.

perl v5.36.0                                       2022-12-06                     AnyEvent::XMPP::Ext::Ping(3pm)