1AnyEvent::XMPP::Ext::PiUnsge(r3)Contributed Perl DocumenAtnaytEivoennt::XMPP::Ext::Ping(3)
2
3
4

NAME

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

SYNOPSIS

9          use AnyEvent::XMPP::Ext::Ping;
10
11          my $con = AnyEvent::XMPP::IM::Connection->new (...);
12          $con->add_extension (my $ping = AnyEvent::XMPP::Ext::Ping->new);
13
14          # this enables auto-timeout of a connection if it didn't answer
15          # within 120 seconds to a ping with a reply
16          $ping->enable_timeout ($con, 120);
17
18          my $cl = AnyEvent::XMPP::Client->new (...);
19          $cl->add_extension (my $ping = AnyEvent::XMPP::Ext::Ping->new);
20
21          # this enables auto-timeout of newly created connections
22          $ping->auto_timeout (120);
23
24          $ping->ping ($con, 'ping_dest@server.tld', sub {
25             my ($time, $error) = @_;
26             if ($error) {
27                # we got an error
28             }
29             # $time is a float (seconds) of the rtt if you got Time::HiRes
30          });
31

DESCRIPTION

33       This extension implements XEP-0199: XMPP Ping.  It allows you to define
34       a automatic ping timeouter that will disconnect dead connections (which
35       didn't reply to a ping after N seconds). See also the documentation of
36       the "enable_timeout" method below.
37
38       It also allows you to send pings to any XMPP entity you like and will
39       measure the time it took if you got Time::HiRes.
40

METHODS

42       new (%args)
43           Creates a new ping handle.
44
45       auto_timeout ($timeout)
46           This method enables automatic connection timeout of new
47           connections. It calls "enable_timeout" (see below) for every new
48           connection that was connected and emitted a "stream_ready" event.
49
50           This is useful if you want connections that have this extension
51           automatically timeouted. In particular this is useful with modules
52           like AnyEvent::XMPP::Client (see also SYNOPSIS above).
53
54       enable_timeout ($con, $timeout)
55           This enables a periodical ping on the connection $con.  $timeout
56           must be the seconds that the ping intervals last.
57
58           If the server which is connected via $con didn't respond within
59           $timeout seconds the connection $con will be disconnected.
60
61           Please note that there already is a basic timeout mechanism for
62           dead TCP connections in AnyEvent::XMPP::Connection, see also the
63           "whitespace_ping_interval" configuration variable for a connection
64           there. It then will depend on TCP timeouts to disconnect the
65           connection.
66
67           Use "enable_timeout" and "auto_timeout" only if you really feel
68           like you need an explicit timeout for your connections.
69
70       ping ($con, $dest, $cb, $timeout)
71           This method sends a ping request to $dest via the
72           AnyEvent::XMPP::Connection in $con. If $dest is undefined the ping
73           will be sent to the connected server.  $cb will be called when
74           either the ping timeouts, an error occurs or the ping result was
75           received. $timeout is an optional timeout for the ping request, if
76           $timeout is not given the default IQ timeout for the connection is
77           the relevant timeout.
78
79           The first argument to $cb will be the seconds of the round trip
80           time for that request (If you have Time::HiRes).  If you don't have
81           Time::HiRes installed the first argument will be undef.
82
83           The second argument to $cb will be either undef if no error occured
84           or a AnyEvent::XMPP::Error::IQ error object.
85
86       ignore_pings ($bool)
87           This method is mostly for testing, it tells this extension to
88           ignore all ping requests and will prevent any response from being
89           sent.
90

AUTHOR

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

95       Copyright 2007, 2008 Robin Redeker, all rights reserved.
96
97       This program is free software; you can redistribute it and/or modify it
98       under the same terms as Perl itself.
99
100
101
102perl v5.12.0                      2009-08-14      AnyEvent::XMPP::Ext::Ping(3)
Impressum