AnyEvent::XMPP::Ext::PUser3Contributed Perl DocumeAnyEvent::XMPP::Ext::Ping(3)NAMEAnyEvent::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.14.1 2009-08-14 AnyEvent::XMPP::Ext::Ping(3)
