.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "AnyEvent::XMPP::Ext::Ping 3" .TH AnyEvent::XMPP::Ext::Ping 3 2024-07-13 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME AnyEvent::XMPP::Ext::Ping \- Implementation of XMPP Ping XEP\-0199 .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& 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\*(Aqt 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, \*(Aqping_dest@server.tld\*(Aq, sub { \& my ($time, $error) = @_; \& if ($error) { \& # we got an error \& } \& # $time is a float (seconds) of the rtt if you got Time::HiRes \& }); .Ve .SH DESCRIPTION .IX Header "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 \f(CW\*(C`enable_timeout\*(C'\fR method below. .PP 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. .SH METHODS .IX Header "METHODS" .IP "\fBnew (%args)\fR" 4 .IX Item "new (%args)" Creates a new ping handle. .IP "\fBauto_timeout ($timeout)\fR" 4 .IX Item "auto_timeout ($timeout)" This method enables automatic connection timeout of new connections. It calls \f(CW\*(C`enable_timeout\*(C'\fR (see below) for every new connection that was connected and emitted a \f(CW\*(C`stream_ready\*(C'\fR event. .Sp 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). .ie n .IP "\fBenable_timeout ($con, \fR\fB$timeout\fR\fB)\fR" 4 .el .IP "\fBenable_timeout ($con, \fR\f(CB$timeout\fR\fB)\fR" 4 .IX Item "enable_timeout ($con, $timeout)" This enables a periodical ping on the connection \f(CW$con\fR. \&\f(CW$timeout\fR must be the seconds that the ping intervals last. .Sp If the server which is connected via \f(CW$con\fR didn't respond within \f(CW$timeout\fR seconds the connection \f(CW$con\fR will be disconnected. .Sp Please note that there already is a basic timeout mechanism for dead TCP connections in AnyEvent::XMPP::Connection, see also the \f(CW\*(C`whitespace_ping_interval\*(C'\fR configuration variable for a connection there. It then will depend on TCP timeouts to disconnect the connection. .Sp Use \f(CW\*(C`enable_timeout\*(C'\fR and \f(CW\*(C`auto_timeout\*(C'\fR only if you really feel like you need an explicit timeout for your connections. .ie n .IP "\fBping ($con, \fR\fB$dest\fR\fB, \fR\fB$cb\fR\fB, \fR\fB$timeout\fR\fB)\fR" 4 .el .IP "\fBping ($con, \fR\f(CB$dest\fR\fB, \fR\f(CB$cb\fR\fB, \fR\f(CB$timeout\fR\fB)\fR" 4 .IX Item "ping ($con, $dest, $cb, $timeout)" This method sends a ping request to \f(CW$dest\fR via the AnyEvent::XMPP::Connection in \f(CW$con\fR. If \f(CW$dest\fR is undefined the ping will be sent to the connected server. \f(CW$cb\fR will be called when either the ping timeouts, an error occurs or the ping result was received. \f(CW$timeout\fR is an optional timeout for the ping request, if \f(CW$timeout\fR is not given the default IQ timeout for the connection is the relevant timeout. .Sp The first argument to \f(CW$cb\fR 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. .Sp The second argument to \f(CW$cb\fR will be either undef if no error occured or a AnyEvent::XMPP::Error::IQ error object. .IP "\fBignore_pings ($bool)\fR" 4 .IX Item "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. .SH AUTHOR .IX Header "AUTHOR" Robin Redeker, \f(CW\*(C`\*(C'\fR, JID: \f(CW\*(C`\*(C'\fR .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2007, 2008 Robin Redeker, all rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.