.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" 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::Connection 3pm" .TH AnyEvent::XMPP::Connection 3pm "2019-02-18" "perl v5.28.1" "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::Connection \- XML stream that implements the XMPP RFC 3920. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use AnyEvent::XMPP::Connection; \& \& my $con = \& AnyEvent::XMPP::Connection\->new ( \& username => "abc", \& domain => "jabber.org", \& resource => "AnyEvent::XMPP" \& ); \& \& $con\->reg_cb (stream_ready => sub { print "XMPP stream ready!\en" }); \& $con\->connect; # will do non\-blocking connect .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module represents a \s-1XMPP\s0 stream as described in \s-1RFC 3920.\s0 You can issue the basic \&\s-1XMPP XML\s0 stanzas with methods like \f(CW\*(C`send_iq\*(C'\fR, \f(CW\*(C`send_message\*(C'\fR and \f(CW\*(C`send_presence\*(C'\fR. .PP And receive events with the \f(CW\*(C`reg_cb\*(C'\fR event framework from the connection. .PP If you need instant messaging stuff please take a look at \f(CW\*(C`AnyEvent::XMPP::IM::Connection\*(C'\fR. .SH "METHODS" .IX Header "METHODS" .IP "\fBnew (%args)\fR" 4 .IX Item "new (%args)" Following arguments can be passed in \f(CW%args\fR: .RS 4 .ie n .IP "language => $tag" 4 .el .IP "language => \f(CW$tag\fR" 4 .IX Item "language => $tag" This should be the language of the human readable contents that will be transmitted over the stream. The default will be 'en'. .Sp Please look in \s-1RFC 3066\s0 how \f(CW$tag\fR should look like. .ie n .IP "jid => $jid" 4 .el .IP "jid => \f(CW$jid\fR" 4 .IX Item "jid => $jid" This can be used to set the settings \f(CW\*(C`username\*(C'\fR, \f(CW\*(C`domain\*(C'\fR (and optionally \f(CW\*(C`resource\*(C'\fR) from a \f(CW$jid\fR. .ie n .IP "username => $username" 4 .el .IP "username => \f(CW$username\fR" 4 .IX Item "username => $username" This is your \f(CW$username\fR (the userpart in the \s-1JID\s0); .Sp Note: You have to take care that the stringprep profile for nodes can be applied at: \f(CW$username\fR. Otherwise the server might signal an error. See AnyEvent::XMPP::Util for utility functions to check this. .Sp \&\fB\s-1NOTE:\s0\fR This field has no effect if \f(CW\*(C`jid\*(C'\fR is given! .ie n .IP "domain => $domain" 4 .el .IP "domain => \f(CW$domain\fR" 4 .IX Item "domain => $domain" If you didn't provide a \f(CW\*(C`jid\*(C'\fR (see above) you have to set the \&\f(CW\*(C`username\*(C'\fR which you want to connect as (see above) and the \&\f(CW$domain\fR to connect to. .Sp \&\fB\s-1NOTE:\s0\fR This field has no effect if \f(CW\*(C`jid\*(C'\fR is given! .ie n .IP "resource => $resource" 4 .el .IP "resource => \f(CW$resource\fR" 4 .IX Item "resource => $resource" If this argument is given \f(CW$resource\fR will be passed as desired resource on resource binding. .Sp Note: You have to take care that the stringprep profile for resources can be applied at: \f(CW$resource\fR. Otherwise the server might signal an error. See AnyEvent::XMPP::Util for utility functions to check this. .ie n .IP "host => $host" 4 .el .IP "host => \f(CW$host\fR" 4 .IX Item "host => $host" This parameter specifies the hostname where we are going to connect to. The default for this is the \f(CW\*(C`domain\*(C'\fR of the \f(CW\*(C`jid\*(C'\fR. .Sp \&\fB\s-1NOTE:\s0\fR To disable \s-1DNS SRV\s0 lookup you need to specify the port \fBnumber\fR yourself. See \f(CW\*(C`port\*(C'\fR below. .ie n .IP "use_host_as_sasl_hostname => $bool" 4 .el .IP "use_host_as_sasl_hostname => \f(CW$bool\fR" 4 .IX Item "use_host_as_sasl_hostname => $bool" This is a special parameter for people who might want to use \s-1GSSAPI SASL\s0 mechanism. It will cause the value of the \f(CW\*(C`host\*(C'\fR parameter (see above) to be passed to the \s-1SASL\s0 mechanisms, instead of the \f(CW\*(C`domain\*(C'\fR of the \s-1JID.\s0 .Sp This flag is provided until support for \s-1XEP 0233\s0 is deployed, which will fix the hostname issue w.r.t. \s-1GSSAPI SASL.\s0 .ie n .IP "port => $port" 4 .el .IP "port => \f(CW$port\fR" 4 .IX Item "port => $port" This is optional, the default value for \f(CW$port\fR is 'xmpp\-client=5222', which will used as \f(CW$service\fR argument to \f(CW\*(C`tcp_connect\*(C'\fR of AnyEvent::Socket. \&\fB\s-1NOTE:\s0\fR If you specify the port number here (instead of 'xmpp\-client=5222'), \&\fBno\fR \s-1DNS SRV\s0 lookup will be done when connecting. .ie n .IP "connect_timeout => $timeout" 4 .el .IP "connect_timeout => \f(CW$timeout\fR" 4 .IX Item "connect_timeout => $timeout" This sets the connection timeout. If the socket connect takes too long a \f(CW\*(C`disconnect\*(C'\fR event will be generated with an appropriate error message. If this argument is not given no timeout is installed for the connects. .ie n .IP "password => $password" 4 .el .IP "password => \f(CW$password\fR" 4 .IX Item "password => $password" This is the password for the \f(CW\*(C`username\*(C'\fR above. .ie n .IP "disable_ssl => $bool" 4 .el .IP "disable_ssl => \f(CW$bool\fR" 4 .IX Item "disable_ssl => $bool" If \f(CW$bool\fR is true no \s-1SSL\s0 will be used. .ie n .IP "old_style_ssl => $bool" 4 .el .IP "old_style_ssl => \f(CW$bool\fR" 4 .IX Item "old_style_ssl => $bool" If \f(CW$bool\fR is true the \s-1TLS\s0 handshake will be initiated when the \s-1TCP\s0 connection was established. This is useful if you have to connect to an old Jabber server, with old-style \s-1SSL\s0 connections on port 5223. .Sp But that practice has been discouraged in \s-1XMPP,\s0 and a \s-1TLS\s0 handshake is done after the \s-1XML\s0 stream has been established. Only use this option if you know what you are doing. .ie n .IP "disable_sasl => $bool" 4 .el .IP "disable_sasl => \f(CW$bool\fR" 4 .IX Item "disable_sasl => $bool" If \f(CW$bool\fR is true \s-1SASL\s0 will \s-1NOT\s0 be used to authenticate with the server, even if it advertises \s-1SASL\s0 through stream features. Alternative authentication methods will be used, such as \s-1IQ\s0 Auth (\s-1XEP\-0078\s0) if the server offers it. .ie n .IP "disable_iq_auth => $bool" 4 .el .IP "disable_iq_auth => \f(CW$bool\fR" 4 .IX Item "disable_iq_auth => $bool" This disables the use of \s-1IQ\s0 Auth (\s-1XEP\-0078\s0) for authentication, you might want to exclude it because it's deprecated and insecure. (However, I want to reach a maximum in compatibility with AnyEvent::XMPP so I'm not disabling this by default. .Sp See also \f(CW\*(C`disable_old_jabber_authentication\*(C'\fR below. .ie n .IP "anal_iq_auth => $bool" 4 .el .IP "anal_iq_auth => \f(CW$bool\fR" 4 .IX Item "anal_iq_auth => $bool" This enables the anal iq auth mechanism that will first look in the stream features before trying to start iq authentication. Yes, servers don't always advertise what they can. I only implemented this option for my test suite. .ie n .IP "disable_old_jabber_authentication => $bool" 4 .el .IP "disable_old_jabber_authentication => \f(CW$bool\fR" 4 .IX Item "disable_old_jabber_authentication => $bool" If \f(CW$bool\fR is a true value, then the \fB\s-1VERY\s0\fR old style authentication method with \fB\s-1VERY\s0\fR old jabber server won't be used when a start tag from the server without version attribute is received. .Sp The \fB\s-1VERY\s0\fR old style authentication method is per default enabled to ensure maximum compatibility with old jabber implementations. The old method works as follows: When a start tag is received from the server with no \&'version' attribute \s-1IQ\s0 Auth (\s-1XEP\-0078\s0) will be initiated to authenticate with the server. .Sp Please note that the old authentication method will fail if \f(CW\*(C`disable_iq_auth\*(C'\fR is true. .ie n .IP "stream_version_override => $version" 4 .el .IP "stream_version_override => \f(CW$version\fR" 4 .IX Item "stream_version_override => $version" \&\fB\s-1NOTE:\s0\fR Only use if you \fBreally\fR know what you are doing! .Sp This will override the stream version which is sent in the \s-1XMPP\s0 stream initiation element. This is currently only used by the tests which set \f(CW$version\fR to '0.9' for testing \s-1IQ\s0 authentication with ejabberd. .ie n .IP "whitespace_ping_interval => $interval" 4 .el .IP "whitespace_ping_interval => \f(CW$interval\fR" 4 .IX Item "whitespace_ping_interval => $interval" This will set the whitespace ping interval (in seconds). The default interval are 60 seconds. You can disable the whitespace ping by setting \f(CW$interval\fR to 0. .RE .RS 4 .RE .IP "\fBconnect ()\fR" 4 .IX Item "connect ()" Try to connect (non blocking) to the domain and port passed in \f(CW\*(C`new\*(C'\fR. .Sp The connection is performed non blocking, so this method will just trigger the connection process. The event \f(CW\*(C`connect\*(C'\fR will be emitted when the connection was successfully established. .Sp If the connection try was not successful a \f(CW\*(C`disconnect\*(C'\fR event will be generated with an error message. .Sp \&\s-1NOTE:\s0 Please note that you can't reconnect a AnyEvent::XMPP::Connection object. You need to recreate it if you want to reconnect. .Sp \&\s-1NOTE:\s0 The \*(L"\s-1XML\*(R"\s0 stream initiation is sent when the connection was successfully connected. .IP "\fBis_connected ()\fR" 4 .IX Item "is_connected ()" Returns true if the connection is still connected and stanzas can be sent. .IP "\fBset_default_iq_timeout ($seconds)\fR" 4 .IX Item "set_default_iq_timeout ($seconds)" This sets the default timeout for \s-1IQ\s0 requests. If the timeout runs out the request will be aborted and the callback called with a AnyEvent::XMPP::Error::IQ object where the \f(CW\*(C`condition\*(C'\fR method returns a special value (see also \f(CW\*(C`condition\*(C'\fR method of AnyEvent::XMPP::Error::IQ). .Sp The default timeout for \s-1IQ\s0 is 60 seconds. .IP "\fBsend_iq ($type, \f(CB$create_cb\fB, \f(CB$result_cb\fB, \f(CB%attrs\fB)\fR" 4 .IX Item "send_iq ($type, $create_cb, $result_cb, %attrs)" This method sends an \s-1IQ XMPP\s0 \fBrequest\fR. .Sp If you want to \fBrespond\fR to a \s-1IQ\s0 request you received via the \f(CW\*(C`iq_set_request_xml\*(C'\fR, and \f(CW\*(C`iq_get_request_xml\*(C'\fR events you have to use the \f(CW\*(C`reply_iq_result\*(C'\fR or \&\f(CW\*(C`reply_iq_error\*(C'\fR methods documented below. .Sp Please take a look at the documentation for \f(CW\*(C`send_iq\*(C'\fR in AnyEvent::XMPP::Writer about the meaning of \f(CW$type\fR, \f(CW$create_cb\fR and \f(CW%attrs\fR (with the exception of the 'timeout' key of \f(CW%attrs\fR, see below). .Sp \&\f(CW$result_cb\fR will be called when a result was received or the timeout reached. The first argument to \f(CW$result_cb\fR will be a AnyEvent::XMPP::Node instance containing the \s-1IQ\s0 result stanza contents. .Sp If the \s-1IQ\s0 resulted in a stanza error the second argument to \f(CW$result_cb\fR will be \f(CW\*(C`undef\*(C'\fR (if the error type was not 'continue') and the third argument will be a AnyEvent::XMPP::Error::IQ object. .Sp The timeout can be set by \f(CW\*(C`set_default_iq_timeout\*(C'\fR or passed separately in the \f(CW%attrs\fR array as the value for the key \f(CW\*(C`timeout\*(C'\fR (timeout in seconds btw.). .Sp This method returns the newly generated id for this iq request. .IP "\fBnext_iq_id\fR" 4 .IX Item "next_iq_id" This method returns the next \s-1IQ\s0 id that will be used. .IP "\fBreply_iq_result ($req_iq_node, \f(CB$create_cb\fB, \f(CB%attrs\fB)\fR" 4 .IX Item "reply_iq_result ($req_iq_node, $create_cb, %attrs)" This method will generate a result reply to the iq request \f(CW\*(C`AnyEvent::XMPP::Node\*(C'\fR in \f(CW$req_iq_node\fR. .Sp Please take a look at the documentation for \f(CW\*(C`send_iq\*(C'\fR in AnyEvent::XMPP::Writer about the meaning \f(CW$create_cb\fR and \f(CW%attrs\fR. .Sp Use \f(CW$create_cb\fR to create the \s-1XML\s0 for the result. .Sp The type for this iq reply is 'result'. .Sp The \f(CW\*(C`to\*(C'\fR attribute of the reply stanza will be set to the \f(CW\*(C`from\*(C'\fR attribute of the \f(CW$req_iq_node\fR. If \f(CW$req_iq_node\fR had no \f(CW\*(C`from\*(C'\fR node it won't be set. If you want to overwrite the \f(CW\*(C`to\*(C'\fR field just pass it via \f(CW%attrs\fR. .IP "\fBreply_iq_error ($req_iq_node, \f(CB$error_type\fB, \f(CB$error\fB, \f(CB%attrs\fB)\fR" 4 .IX Item "reply_iq_error ($req_iq_node, $error_type, $error, %attrs)" This method will generate an error reply to the iq request \f(CW\*(C`AnyEvent::XMPP::Node\*(C'\fR in \f(CW$req_iq_node\fR. .Sp \&\f(CW$error_type\fR is one of 'cancel', 'continue', 'modify', 'auth' and 'wait'. \&\f(CW$error\fR is one of the defined error conditions described in \&\f(CW\*(C`write_error_tag\*(C'\fR method of AnyEvent::XMPP::Writer. .Sp Please take a look at the documentation for \f(CW\*(C`send_iq\*(C'\fR in AnyEvent::XMPP::Writer about the meaning of \f(CW%attrs\fR. .Sp The type for this iq reply is 'error'. .Sp The \f(CW\*(C`to\*(C'\fR attribute of the reply stanza will be set to the \f(CW\*(C`from\*(C'\fR attribute of the \f(CW$req_iq_node\fR. If \f(CW$req_iq_node\fR had no \f(CW\*(C`from\*(C'\fR node it won't be set. If you want to overwrite the \f(CW\*(C`to\*(C'\fR field just pass it via \f(CW%attrs\fR. .IP "\fBauthenticate\fR" 4 .IX Item "authenticate" This method should be called after the \f(CW\*(C`stream_pre_authentication\*(C'\fR event was emitted to continue authentication of the stream. .Sp Usually this method only has to be called when you want to register before you authenticate. See also the documentation of the \f(CW\*(C`stream_pre_authentication\*(C'\fR event below. .IP "\fBsend_presence ($type, \f(CB$create_cb\fB, \f(CB%attrs\fB)\fR" 4 .IX Item "send_presence ($type, $create_cb, %attrs)" This method sends a presence stanza, for the meanings of \f(CW$type\fR, \f(CW$create_cb\fR and \f(CW%attrs\fR please take a look at the documentation for \f(CW\*(C`send_presence\*(C'\fR method of AnyEvent::XMPP::Writer. .Sp This methods does attach an id attribute to the presence stanza and will return the id that was used (so you can react on possible replies). .IP "\fBsend_message ($to, \f(CB$type\fB, \f(CB$create_cb\fB, \f(CB%attrs\fB)\fR" 4 .IX Item "send_message ($to, $type, $create_cb, %attrs)" This method sends a message stanza, for the meanings of \f(CW$to\fR, \f(CW$type\fR, \f(CW$create_cb\fR and \f(CW%attrs\fR please take a look at the documentation for \f(CW\*(C`send_message\*(C'\fR method of AnyEvent::XMPP::Writer. .Sp This methods does attach an id attribute to the message stanza and will return the id that was used (so you can react on possible replies). .IP "\fBdo_rebind ($resource)\fR" 4 .IX Item "do_rebind ($resource)" In case you got a \f(CW\*(C`bind_error\*(C'\fR event and want to retry binding you can call this function to set a new \f(CW$resource\fR and retry binding. .Sp If it fails again you can call this again. Becareful not to end up in a loop! .Sp If binding was successful the \f(CW\*(C`stream_ready\*(C'\fR event will be generated. .IP "\fBjid\fR" 4 .IX Item "jid" After the stream has been bound to a resource the \s-1JID\s0 can be retrieved via this method. .IP "\fBfeatures\fR" 4 .IX Item "features" Returns the last received tag in form of an AnyEvent::XMPP::Node object. .IP "\fBstream_id\fR" 4 .IX Item "stream_id" This is the \s-1ID\s0 of this stream that was given us by the server. .SH "EVENTS" .IX Header "EVENTS" The AnyEvent::XMPP::Connection class is derived from the Object::Event class, and thus inherits the event callback registering system from it. Consult the documentation of Object::Event about more details. .PP \&\s-1NODE:\s0 Every callback gets as it's first argument the AnyEvent::XMPP::Connection object. The further callback arguments are described in the following listing of events. .PP These events can be registered on with \f(CW\*(C`reg_cb\*(C'\fR: .ie n .IP "stream_features => $node" 4 .el .IP "stream_features => \f(CW$node\fR" 4 .IX Item "stream_features => $node" This event is sent when a stream feature () tag is received. \f(CW$node\fR is the AnyEvent::XMPP::Node object that represents the tag. .IP "stream_pre_authentication" 4 .IX Item "stream_pre_authentication" This event is emitted after \s-1TLS/SSL\s0 was initiated (if enabled) and before any authentication happened. .Sp The return value of the first event callback that is called decides what happens next. If it is true value the authentication continues. If it is undef or a false value authentication is stopped and you need to call \f(CW\*(C`authentication\*(C'\fR later. value .Sp This event is usually used when you want to do in-band registration, see also AnyEvent::XMPP::Ext::Registration. .ie n .IP "stream_ready => $jid" 4 .el .IP "stream_ready => \f(CW$jid\fR" 4 .IX Item "stream_ready => $jid" This event is sent if the \s-1XML\s0 stream has been established (and resources have been bound) and is ready for transmitting regular stanzas. .Sp \&\f(CW$jid\fR is the bound jabber id. .ie n .IP "error => $error" 4 .el .IP "error => \f(CW$error\fR" 4 .IX Item "error => $error" This event is generated whenever some error occured. \&\f(CW$error\fR is an instance of AnyEvent::XMPP::Error. Trivial error reporting may look like this: .Sp .Vb 1 \& $con\->reg_cb (error => sub { warn "xmpp error: " . $_[1]\->string . "\en" }); .Ve .Sp Basically this event is a collect event for all other error events. .ie n .IP "stream_error => $error" 4 .el .IP "stream_error => \f(CW$error\fR" 4 .IX Item "stream_error => $error" This event is sent if a \s-1XML\s0 stream error occured. \f(CW$error\fR is a AnyEvent::XMPP::Error::Stream object. .ie n .IP "xml_parser_error => $error" 4 .el .IP "xml_parser_error => \f(CW$error\fR" 4 .IX Item "xml_parser_error => $error" This event is generated whenever the parser trips over \s-1XML\s0 that it can't read. \f(CW$error\fR is a AnyEvent::XMPP::Error::Parser object. .IP "tls_error" 4 .IX Item "tls_error" This event is emitted when a \s-1TLS\s0 error occured on \s-1TLS\s0 negotiation. After this the connection will be disconnected. .ie n .IP "sasl_error => $error" 4 .el .IP "sasl_error => \f(CW$error\fR" 4 .IX Item "sasl_error => $error" This event is emitted on \s-1SASL\s0 authentication error. .ie n .IP "iq_auth_error => $error" 4 .el .IP "iq_auth_error => \f(CW$error\fR" 4 .IX Item "iq_auth_error => $error" This event is emitted when \s-1IQ\s0 authentication (\s-1XEP\-0078\s0) failed. .ie n .IP "bind_error => $error, $resource" 4 .el .IP "bind_error => \f(CW$error\fR, \f(CW$resource\fR" 4 .IX Item "bind_error => $error, $resource" This event is generated when the stream was unable to bind to any or the in \f(CW\*(C`new\*(C'\fR specified resource. \f(CW$error\fR is a AnyEvent::XMPP::Error::IQ object. \f(CW$resource\fR is the errornous resource string or undef if none was received. .Sp The \f(CW\*(C`condition\*(C'\fR of the \f(CW$error\fR might be one of: 'bad\-request', \&'not\-allowed' or 'conflict'. .Sp Node: this is untested, I couldn't get the server to send a bind error to test this. .ie n .IP "connect => $host, $port" 4 .el .IP "connect => \f(CW$host\fR, \f(CW$port\fR" 4 .IX Item "connect => $host, $port" This event is generated when a successful \s-1TCP\s0 connect was performed to the domain passed to \f(CW\*(C`new\*(C'\fR. .Sp Note: \f(CW$host\fR and \f(CW$port\fR might be different from the domain you passed to \&\f(CW\*(C`new\*(C'\fR if \f(CW\*(C`connect\*(C'\fR performed a \s-1SRV RR\s0 lookup. .Sp If this connection is lost a \f(CW\*(C`disconnect\*(C'\fR will be generated with the same \&\f(CW$host\fR and \f(CW$port\fR. .ie n .IP "disconnect => $host, $port, $message" 4 .el .IP "disconnect => \f(CW$host\fR, \f(CW$port\fR, \f(CW$message\fR" 4 .IX Item "disconnect => $host, $port, $message" This event is generated when the \s-1TCP\s0 connection was lost or another error occurred while writing or reading from it. .Sp \&\f(CW$message\fR is a human readable error message for the failure. \&\f(CW$host\fR and \f(CW$port\fR were the host and port we were connected to. .Sp Note: \f(CW$host\fR and \f(CW$port\fR might be different from the domain you passed to \&\f(CW\*(C`new\*(C'\fR if \f(CW\*(C`connect\*(C'\fR performed a \s-1SRV RR\s0 lookup. .ie n .IP "recv_stanza_xml => $node, $rstop" 4 .el .IP "recv_stanza_xml => \f(CW$node\fR, \f(CW$rstop\fR" 4 .IX Item "recv_stanza_xml => $node, $rstop" This event is generated before any processing of a \*(L"\s-1XML\*(R"\s0 stanza happens. \&\f(CW$node\fR is the node of the stanza that is being processed, it's of type AnyEvent::XMPP::Node. .Sp This method might not be as handy for debugging purposes as \f(CW\*(C`debug_recv\*(C'\fR. .Sp If you want to handle the stanza yourself and don't want this module to take care of it set a true value to the scalar referenced by \f(CW$rstop\fR. .ie n .IP "send_stanza_data => $data" 4 .el .IP "send_stanza_data => \f(CW$data\fR" 4 .IX Item "send_stanza_data => $data" This event is generated shortly before data is sent to the socket. \&\f(CW$data\fR contains a complete \*(L"\s-1XML\*(R"\s0 stanza or the end of stream closing tag. This method is useful for debugging purposes and I recommend using XML::Twig or something like that to display it nicely. .Sp See also the event \f(CW\*(C`debug_send\*(C'\fR. .ie n .IP "debug_send => $data" 4 .el .IP "debug_send => \f(CW$data\fR" 4 .IX Item "debug_send => $data" This method is invoked whenever data is written out. This event is mostly the same as \f(CW\*(C`send_stanza_data\*(C'\fR. .ie n .IP "debug_recv => $data" 4 .el .IP "debug_recv => \f(CW$data\fR" 4 .IX Item "debug_recv => $data" This method is invoked whenever a chunk of data was received. .Sp It works to filter \f(CW$data\fR through XML::Twig for debugging display purposes sometimes, but as \f(CW$data\fR is some arbitrary chunk of bytes you might get a \s-1XML\s0 parse error (did I already mention that \s-1XMPP\s0's application of \*(L"\s-1XML\*(R"\s0 sucks?). .Sp So you might want to use \f(CW\*(C`recv_stanza_xml\*(C'\fR to detect complete stanzas. Unfortunately \f(CW\*(C`recv_stanza_xml\*(C'\fR doesn't have the bytes anymore and just a data structure (AnyEvent::XMPP::Node). .IP "send_buffer_empty" 4 .IX Item "send_buffer_empty" This event is \s-1VERY\s0 useful if you want to wait (or at least be notified) when the output buffer is empty. If you got a bunch of messages to sent or even one and you want to do something when the output buffer is empty, you can wait for this event. It is emitted every time the output buffer is completely written out to the kernel. .Sp Here is an example: .Sp .Vb 4 \& $con\->reg_cb (send_buffer_empty => sub { \& $con\->disconnect ("wrote message, going to disconnect now..."); \& }); \& $con\->send_message ("Test message!" => \*(Aqelmex@jabber.org\*(Aq, undef, \*(Aqchat\*(Aq); .Ve .ie n .IP "presence_xml => $node" 4 .el .IP "presence_xml => \f(CW$node\fR" 4 .IX Item "presence_xml => $node" This event is sent when a presence stanza is received. \f(CW$node\fR is the AnyEvent::XMPP::Node object that represents the tag. .Sp If you want to overtake the handling of the stanza, see \f(CW\*(C`iq_xml\*(C'\fR below. .ie n .IP "message_xml => $node" 4 .el .IP "message_xml => \f(CW$node\fR" 4 .IX Item "message_xml => $node" This event is sent when a message stanza is received. \f(CW$node\fR is the AnyEvent::XMPP::Node object that represents the tag. .Sp If you want to overtake the handling of the stanza, see \f(CW\*(C`iq_xml\*(C'\fR below. .ie n .IP "iq_xml => $node" 4 .el .IP "iq_xml => \f(CW$node\fR" 4 .IX Item "iq_xml => $node" This event is emitted when a iq stanza arrives. \f(CW$node\fR is the AnyEvent::XMPP::Node object that represents the tag. .Sp If you want to overtake the handling of a stanza, you should register a callback for the \f(CW\*(C`before_iq_xml\*(C'\fR event and call the \&\f(CW\*(C`stop_event\*(C'\fR method. See also Object::Event. This is an example: .Sp .Vb 2 \& $con\->reg_cb (before_iq_xml => sub { \& my ($con, $node) = @_; \& \& if (...) { \& # and stop_event will stop internal handling of the stanza: \& $con\->stop_event; \& } \& }); .Ve .Sp Please note that if you overtake handling of a stanza none of the internal handling of that stanza will be done. That means you won't get events like \f(CW\*(C`iq_set_request_xml\*(C'\fR anymore. .ie n .IP "iq_set_request_xml => $node, $rhandled" 4 .el .IP "iq_set_request_xml => \f(CW$node\fR, \f(CW$rhandled\fR" 4 .IX Item "iq_set_request_xml => $node, $rhandled" .PD 0 .ie n .IP "iq_get_request_xml => $node, $rhandled" 4 .el .IP "iq_get_request_xml => \f(CW$node\fR, \f(CW$rhandled\fR" 4 .IX Item "iq_get_request_xml => $node, $rhandled" .PD These events are sent when an iq request stanza of type 'get' or 'set' is received. \&\f(CW$type\fR will either be 'get' or 'set' and \f(CW$node\fR will be the AnyEvent::XMPP::Node object of the iq tag. .Sp To signal the stanza was handled set the scalar referenced by \f(CW$rhandled\fR to a true value. If the stanza was not handled an error iq will be generated. .ie n .IP "iq_result_cb_exception => $exception" 4 .el .IP "iq_result_cb_exception => \f(CW$exception\fR" 4 .IX Item "iq_result_cb_exception => $exception" If the \f(CW$result_cb\fR of a \f(CW\*(C`send_iq\*(C'\fR operation somehow threw a exception or failed this event will be generated. .ie n .IP "send_iq_hook => $id, $type, $attrs, \e@create_cb" 4 .el .IP "send_iq_hook => \f(CW$id\fR, \f(CW$type\fR, \f(CW$attrs\fR, \e@create_cb" 4 .IX Item "send_iq_hook => $id, $type, $attrs, @create_cb" This event lets you add any desired number of additional create callbacks to a \s-1IQ\s0 stanza that is about to be sent. .Sp \&\f(CW$id\fR, \f(CW$type\fR are described in the documentation of \f(CW\*(C`send_iq\*(C'\fR of AnyEvent::XMPP::Writer. \f(CW$attrs\fR is the hashref to the \f(CW%attrs\fR hash that can be passed to \f(CW\*(C`send_iq\*(C'\fR and also has the exact same semantics as described in the documentation of \f(CW\*(C`send_iq\*(C'\fR. .Sp You can push values into \f(CW\*(C`create_cb\*(C'\fR (as documented for \f(CW\*(C`send_iq\*(C'\fR), for example a callback that fills the \s-1IQ.\s0 .Sp Example: .Sp .Vb 12 \& # this appends a element to all outgoing IQs \& # and also a element to all outgoing IQs \& $con\->reg_cb (send_iq_hook => sub { \& my ($con, $id, $type, $attrs, $create_cb) = @_; \& push @$create_cb, sub { \& my $w = shift; # $w is a XML::Writer instance \& $w\->emptyTag (\*(Aqtest\*(Aq); \& }; \& push @$create_cb, { \& node => { name => "test2" } # see also simxml() defined in AnyEvent::XMPP::Util \& }; \& }); .Ve .ie n .IP "send_message_hook => $id, $to, $type, $attrs, \e@create_cb" 4 .el .IP "send_message_hook => \f(CW$id\fR, \f(CW$to\fR, \f(CW$type\fR, \f(CW$attrs\fR, \e@create_cb" 4 .IX Item "send_message_hook => $id, $to, $type, $attrs, @create_cb" This event lets you add any desired number of additional create callbacks to a message stanza that is about to be sent. .Sp \&\f(CW$id\fR, \f(CW$to\fR, \f(CW$type\fR and the hashref \f(CW$attrs\fR are described in the documentation for \f(CW\*(C`send_message\*(C'\fR of AnyEvent::XMPP::Writer (\f(CW$attrs\fR is \f(CW%attrs\fR there). .Sp To actually append something you need to push into \f(CW\*(C`create_cb\*(C'\fR as described in the \f(CW\*(C`send_iq_hook\*(C'\fR event above. .ie n .IP "send_presence_hook => $id, $type, $attrs, \e@create_cb" 4 .el .IP "send_presence_hook => \f(CW$id\fR, \f(CW$type\fR, \f(CW$attrs\fR, \e@create_cb" 4 .IX Item "send_presence_hook => $id, $type, $attrs, @create_cb" This event lets you add any desired number of additional create callbacks to a presence stanza that is about to be sent. .Sp \&\f(CW$id\fR, \f(CW$type\fR and the hashref \f(CW$attrs\fR are described in the documentation for \f(CW\*(C`send_presence\*(C'\fR of AnyEvent::XMPP::Writer (\f(CW$attrs\fR is \f(CW%attrs\fR there). .Sp To actually append something you need to push into \f(CW\*(C`create_cb\*(C'\fR as described in the \f(CW\*(C`send_iq_hook\*(C'\fR event above. .SH "AUTHOR" .IX Header "AUTHOR" Robin Redeker, \f(CW\*(C`\*(C'\fR, \s-1JID:\s0 \f(CW\*(C`\*(C'\fR .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" melo \- minor fixes .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.