NAME

SYNOPSIS

   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!\n" });
   $con->connect; # will do non-blocking connect

DESCRIPTION

And receive events with the "reg_cb" event framework from the connection.

If you need instant messaging stuff please take a look at "AnyEvent::XMPP::IM::Connection".

METHODS

new (%args)

Following arguments can be passed in %args:

connect ()

Try to connect (non blocking) to the domain and port passed in "new".

The connection is performed non blocking, so this method will just trigger the connection process. The event "connect" will be emitted when the connection was successfully established.

If the connection try was not successful a "disconnect" event will be generated with an error message.

NOTE: Please note that you can't reconnect a AnyEvent::XMPP::Connection object. You need to recreate it if you want to reconnect.

NOTE: The "XML" stream initiation is sent when the connection was successfully connected.

is_connected ()

Returns true if the connection is still connected and stanzas can be sent.

set_default_iq_timeout ($seconds)

This sets the default timeout for IQ requests. If the timeout runs out the request will be aborted and the callback called with a AnyEvent::XMPP::Error::IQ object where the "condition" method returns a special value (see also "condition" method of AnyEvent::XMPP::Error::IQ).

The default timeout for IQ is 60 seconds.

send_iq ($type, $create_cb, $result_cb, %attrs)

This method sends an IQ XMPP request.

If you want to respond to a IQ request you received via the "iq_set_request_xml", and "iq_get_request_xml" events you have to use the "reply_iq_result" or "reply_iq_error" methods documented below.

Please take a look at the documentation for "send_iq" in AnyEvent::XMPP::Writer about the meaning of $type, $create_cb and %attrs (with the exception of the 'timeout' key of %attrs, see below).

$result_cb will be called when a result was received or the timeout reached. The first argument to $result_cb will be a AnyEvent::XMPP::Node instance containing the IQ result stanza contents.

If the IQ resulted in a stanza error the second argument to $result_cb will be "undef" (if the error type was not 'continue') and the third argument will be a AnyEvent::XMPP::Error::IQ object.

The timeout can be set by "set_default_iq_timeout" or passed separately in the %attrs array as the value for the key "timeout" (timeout in seconds btw.).

This method returns the newly generated id for this iq request.

next_iq_id

This method returns the next IQ id that will be used.

reply_iq_result ($req_iq_node, $create_cb, %attrs )

This method will generate a result reply to the iq request "AnyEvent::XMPP::Node" in $req_iq_node.

Please take a look at the documentation for "send_iq" in AnyEvent::XMPP::Writer about the meaning $create_cb and %attrs.

Use $create_cb to create the XML for the result.

The type for this iq reply is 'result'.

The "to" attribute of the reply stanza will be set to the "from" attribute of the $req_iq_node. If $req_iq_node had no "from" node it won't be set. If you want to overwrite the "to" field just pass it via %attrs.

reply_iq_error ($req_iq_node, $error_type, $error , %attrs)

This method will generate an error reply to the iq request "AnyEvent::XMPP::Node" in $req_iq_node.

$error_type is one of 'cancel', 'continue', 'modify', 'auth' and 'wait'. $error is one of the defined error conditions described in "write_error_tag" method of AnyEvent::XMPP::Writer.

Please take a look at the documentation for "send_iq" in AnyEvent::XMPP::Writer about the meaning of %attrs.

The type for this iq reply is 'error'.

The "to" attribute of the reply stanza will be set to the "from" attribute of the $req_iq_node. If $req_iq_node had no "from" node it won't be set. If you want to overwrite the "to" field just pass it via %attrs.

authenticate

This method should be called after the "stream_pre_authentication" event was emitted to continue authentication of the stream.

Usually this method only has to be called when you want to register before you authenticate. See also the documentation of the "stream_pre_authentication" event below.

send_presence ($type, $create_cb, %attrs)

This method sends a presence stanza, for the meanings of $type, $create_cb and %attrs please take a look at the documentation for "send_presence" method of AnyEvent::XMPP::Writer.

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).

send_message ($to, $type, $create_cb, %attrs)

This method sends a message stanza, for the meanings of $to, $type, $create_cb and %attrs please take a look at the documentation for "send_message" method of AnyEvent::XMPP::Writer.

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).

do_rebind ($resource)

In case you got a "bind_error" event and want to retry binding you can call this function to set a new $resource and retry binding.

If it fails again you can call this again. Becareful not to end up in a loop!

If binding was successful the "stream_ready" event will be generated.

jid

After the stream has been bound to a resource the JID can be retrieved via this method.

features

Returns the last received <features> tag in form of an AnyEvent::XMPP::Node object.

stream_id

This is the ID of this stream that was given us by the server.

EVENTS

NODE: 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.

These events can be registered on with "reg_cb":

stream_features => $node

This event is sent when a stream feature (<features>) tag is received. $node is the AnyEvent::XMPP::Node object that represents the <features> tag.

stream_pre_authentication

This event is emitted after TLS/SSL was initiated (if enabled) and before any authentication happened.

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 "authentication" later. value

This event is usually used when you want to do in-band registration, see also AnyEvent::XMPP::Ext::Registration.

stream_ready => $jid

This event is sent if the XML stream has been established (and resources have been bound) and is ready for transmitting regular stanzas.

$jid is the bound jabber id.

error => $error

This event is generated whenever some error occured. $error is an instance of AnyEvent::XMPP::Error. Trivial error reporting may look like this:

   $con->reg_cb (error => sub { warn "xmpp error: " . $_[1]->string . "\n" });
    

Basically this event is a collect event for all other error events.

stream_error => $error

This event is sent if a XML stream error occured. $error is a AnyEvent::XMPP::Error::Stream object.

xml_parser_error => $error

This event is generated whenever the parser trips over XML that it can't read. $error is a AnyEvent::XMPP::Error::Parser object.

tls_error

This event is emitted when a TLS error occured on TLS negotiation. After this the connection will be disconnected.

sasl_error => $error

This event is emitted on SASL authentication error.

iq_auth_error => $error

This event is emitted when IQ authentication (XEP-0078) failed.

bind_error => $error, $resource

This event is generated when the stream was unable to bind to any or the in "new" specified resource. $error is a AnyEvent::XMPP::Error::IQ object. $resource is the errornous resource string or undef if none was received.

The "condition" of the $error might be one of: 'bad-request', 'not-allowed' or 'conflict'.

Node: this is untested, I couldn't get the server to send a bind error to test this.

connect => $host, $port

This event is generated when a successful TCP connect was performed to the domain passed to "new".

Note: $host and $port might be different from the domain you passed to "new" if "connect" performed a SRV RR lookup.

If this connection is lost a "disconnect" will be generated with the same $host and $port.

disconnect => $host, $port, $message

This event is generated when the TCP connection was lost or another error occurred while writing or reading from it.

$message is a human readable error message for the failure. $host and $port were the host and port we were connected to.

Note: $host and $port might be different from the domain you passed to "new" if "connect" performed a SRV RR lookup.

recv_stanza_xml => $node, $rstop

This event is generated before any processing of a "XML" stanza happens. $node is the node of the stanza that is being processed, it's of type AnyEvent::XMPP::Node.

This method might not be as handy for debugging purposes as "debug_recv".

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 $rstop.

send_stanza_data => $data

This event is generated shortly before data is sent to the socket. $data contains a complete "XML" 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.

See also the event "debug_send".

debug_send => $data

This method is invoked whenever data is written out. This event is mostly the same as "send_stanza_data".

debug_recv => $data

This method is invoked whenever a chunk of data was received.

It works to filter $data through XML::Twig for debugging display purposes sometimes, but as $data is some arbitrary chunk of bytes you might get a XML parse error (did I already mention that XMPP's application of "XML" sucks?).

So you might want to use "recv_stanza_xml" to detect complete stanzas. Unfortunately "recv_stanza_xml" doesn't have the bytes anymore and just a data structure (AnyEvent::XMPP::Node).

send_buffer_empty

This event is VERY 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.

Here is an example:

   $con->reg_cb (send_buffer_empty => sub {
      $con->disconnect ("wrote message, going to disconnect now...");
   });
   $con->send_message ("Test message!" => 'elmex@jabber.org', undef, 'chat');
    

presence_xml => $node

This event is sent when a presence stanza is received. $node is the AnyEvent::XMPP::Node object that represents the <presence> tag.

If you want to overtake the handling of the stanza, see "iq_xml" below.

message_xml => $node

This event is sent when a message stanza is received. $node is the AnyEvent::XMPP::Node object that represents the <message> tag.

If you want to overtake the handling of the stanza, see "iq_xml" below.

iq_xml => $node

This event is emitted when a iq stanza arrives. $node is the AnyEvent::XMPP::Node object that represents the <iq> tag.

If you want to overtake the handling of a stanza, you should register a callback for the "before_iq_xml" event and call the "stop_event" method. See also Object::Event. This is an example:

   $con->reg_cb (before_iq_xml => sub {
      my ($con, $node) = @_;

      if (...) {
         # and stop_event will stop internal handling of the stanza:
         $con->stop_event;
      }
   });
    

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 "iq_set_request_xml" anymore.

iq_set_request_xml => $node, $rhandled

iq_get_request_xml => $node, $rhandled

These events are sent when an iq request stanza of type 'get' or 'set' is received. $type will either be 'get' or 'set' and $node will be the AnyEvent::XMPP::Node object of the iq tag.

To signal the stanza was handled set the scalar referenced by $rhandled to a true value. If the stanza was not handled an error iq will be generated.

iq_result_cb_exception => $exception

If the $result_cb of a "send_iq" operation somehow threw a exception or failed this event will be generated.

send_iq_hook => $id, $type, $attrs, \@create_cb

This event lets you add any desired number of additional create callbacks to a IQ stanza that is about to be sent.

$id, $type are described in the documentation of "send_iq" of AnyEvent::XMPP::Writer. $attrs is the hashref to the %attrs hash that can be passed to "send_iq" and also has the exact same semantics as described in the documentation of "send_iq".

You can push values into "create_cb" (as documented for "send_iq"), for example a callback that fills the IQ.

Example:

   # this appends a <test/> element to all outgoing IQs
   # and also a <test2/> 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 ('test');
      };
      push @$create_cb, {
         node => { name => "test2" } # see also simxml() defined in AnyEvent::XMPP::Util
      };
   });
    

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.

$id, $to, $type and the hashref $attrs are described in the documentation for "send_message" of AnyEvent::XMPP::Writer ($attrs is %attrs there).

To actually append something you need to push into "create_cb" as described in the "send_iq_hook" event above.

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.

$id, $type and the hashref $attrs are described in the documentation for "send_presence" of AnyEvent::XMPP::Writer ($attrs is %attrs there).

To actually append something you need to push into "create_cb" as described in the "send_iq_hook" event above.

AUTHOR

CONTRIBUTORS

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.