.\" Automatically generated by Pod::Man 4.14 (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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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 3pm" .TH AnyEvent::XMPP::Ext::Ping 3pm "2022-12-06" "perl v5.36.0" "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 \s-1XEP\-0199: XMPP\s0 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 \s-1XMPP\s0 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 \s-1SYNOPSIS\s0 above). .IP "\fBenable_timeout ($con, \f(CB$timeout\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 \s-1TCP\s0 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 \s-1TCP\s0 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. .IP "\fBping ($con, \f(CB$dest\fB, \f(CB$cb\fB, \f(CB$timeout\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 \s-1IQ\s0 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, \s-1JID:\s0 \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.