/ 
Net-XMPP2-0.02
/ Net::XMPP2::Connection

NAME

Net::XMPP2::Connection - XML stream that implements the XMPP RFC 3920.

SYNOPSIS

use Net::XMPP2::Connection;

my $con =
   Net::XMPP2::Connection->new (
      username => "abc",
      domain => "jabber.org",
      resource => "Net::XMPP2"
   );

$con->connect or die "Couldn't connect to jabber.org: $!";
$con->init;
$con->reg_cb (stream_ready => sub { print "XMPP stream ready!\n" });

DESCRIPTION

This module represents a XMPP stream as described in RFC 3920. You can issue the basic XMPP XML stanzas with methods like send_iq, send_message and send_presence.

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

If you need instant messaging stuff please take a look at Net::XMPP2::IM::Connection.

METHODS

new (%args)

Following arguments can be passed in %args:

language => $tag

This should be the language of the human readable contents that will be transmitted over the stream. The default will be 'en'.

Please look in RFC 3066 how $tag should look like.

jid => $jid

This can be used to set the settings username, domain (and optionally resource) from a $jid.

resource => $resource

If this argument is given $resource will be passed as desired resource on resource binding.

Note: You have to take care that the stringprep profile for resources can be applied at: $resource. Otherwise the server might signal an error. See Net::XMPP2::Util for utility functions to check this.

domain => $domain

This is the destination host we are going to connect to. As the connection won't be automatically connected use connect to initiate the connect.

Note: A SRV RR lookup will be performed to discover the real hostname and port to connect to. See also connect.

override_host => $host =item override_port => $port

This will be used as override to connect to.

port => $port

This is optional, the default port is 5222.

Note: A SRV RR lookup will be performed to discover the real hostname and port to connect to. See also connect.

username => $username

This is your $username (the userpart in the JID);

Note: You have to take care that the stringprep profile for nodes can be applied at: $username. Otherwise the server might signal an error. See Net::XMPP2::Util for utility functions to check this.

password => $password

This is the password for the username above.

disable_ssl => $bool

If $bool is true no SSL will be used.

connect ($no_srv_rr)

Try to connect to the domain and port passed in new.

A SRV RR lookup will be performed on the domain to discover the host and port to use. If you don't want this set $no_srv_rr to a true value. $no_srv_rr is false by default.

As the SRV RR lookup might return multiple host and you fail to connect to one you might just call this function again to try a different host.

If connect was successful and we connected a true value is returned. If the connect was unsuccessful undef is returned and $! will be set to the error that occured while connecting.

If you want to know whether further connection attempts might be more successful (as SRV RR lookup may return multiple hosts) call may_try_connect (see also may_try_connect).

Note that an internal list will be kept of tried hosts. Use reset_connect_tries to reset the internal list of tried hosts.

may_try_connect

Returns the number of left alternatives of hosts to connect to for the domain passed to new.

An internal list of tried hosts will be managed by connect and those hosts will be ignored by a SRV RR lookup (which will be done if you call this function).

Use reset_connect_tries to reset the internal list of tried hosts.

reset_connect_tries

This function resets the internal list of tried hosts for connect. See also connect.

init ()

Initiate the XML stream.

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 Net::XMPP2::Error::IQ object where the condition method returns a special value (see also condition method of Net::XMPP2::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.

Please take a look at the documentation for send_iq in Net::XMPP2::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 Net::XMPP2::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 Net::XMPP2::Error::IQ object.

The timeout can be set by set_default_iq_timeout or passed seperatly 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.

reply_iq_result ($req_iq_node, $create_cb, %attrs)

This method will generate a result reply to the iq request Net::XMPP2::Node in $req_iq_node.

Please take a look at the documentation for send_iq in Net::XMPP2::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'.

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

This method will generate an error reply to the iq request Net::XMPP2::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 Net::XMPP2::Writer.

Please take a look at the documentation for send_iq in Net::XMPP2::Writer about the meaning of %attrs.

The type for this iq reply is 'error'.

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 Net::XMPP2::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).

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

This method sends a presence stanza, for the meanings of $to, $type, $create_cb and %attrs please take a look at the documentation for send_message method of Net::XMPP2::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 Net::XMPP2::Node object.

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 Net::XMPP2::Node object that represents the <features> tag.

stream_pre_authentication => $rcontinue

This event is emitted after TLS/SSL was initiated (if enabled) and before any authentication happened. $rcontinue is a reference to a scalar that per default holds a true value. If that scalar is true the authentication will continue after handling this event. If you set $$rcontinue to a false value the authentication will stop and you have to call the authenticate method later.

This event is usually used when you want to do in-band registration, see also Net::XMPP2::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 Net::XMPP2::Error. Trivial error reporting may look like this:

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

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 Net::XMPP2::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 Net::XMPP2::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.

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 Net::XMPP2::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 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 connection was lost or another error occured while writing or reading from it.

$message is a humand 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

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 Net::XMPP2::Node.

This method might not be as handy for debuggin purposes as debug_recv.

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 incoked 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 datastructure (Net::XMPP2::Node).

presence_xml => $node

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

message_xml => $node

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

iq_xml => $node

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

iq_set_request_xml => $node, $handled_ref
iq_get_request_xml => $node, $handled_ref

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 Net::XMPP2::Node object of the iq tag.

If $$handled_ref is true an event handler should not handle this message anymore.

If one of the event handlers handled this message the scalar pointed at by the reference in $handled_ref should be set to 1 true value. If $$handled_ref is still false after all event handlers were executed 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.

AUTHOR

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

COPYRIGHT & LICENSE

Copyright 2007 Robin Redeker, all rights reserved.

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