| AnyEvent::XMPP::Connection(3pm) | User Contributed Perl Documentation | AnyEvent::XMPP::Connection(3pm) |
AnyEvent::XMPP::Connection - XML stream that implements the XMPP RFC 3920.
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
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 "AnyEvent::XMPP::IM::Connection".
Please look in RFC 3066 how $tag should look like.
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 AnyEvent::XMPP::Util for utility functions to check this.
NOTE: This field has no effect if "jid" is given!
NOTE: This field has no effect if "jid" is given!
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 AnyEvent::XMPP::Util for utility functions to check this.
NOTE: To disable DNS SRV lookup you need to specify the port number yourself. See "port" below.
This flag is provided until support for XEP 0233 is deployed, which will fix the hostname issue w.r.t. GSSAPI SASL.
But that practice has been discouraged in XMPP, and a TLS handshake is done after the XML stream has been established. Only use this option if you know what you are doing.
See also "disable_old_jabber_authentication" below.
The VERY old style authentication method is per default enabled to ensure maximum compatibility with old jabber implementations. The old method works as follows: When a <stream> start tag is received from the server with no 'version' attribute IQ Auth (XEP-0078) will be initiated to authenticate with the server.
Please note that the old authentication method will fail if "disable_iq_auth" is true.
This will override the stream version which is sent in the XMPP stream initiation element. This is currently only used by the tests which set $version to '0.9' for testing IQ authentication with ejabberd.
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.
The default timeout for IQ is 60 seconds.
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.
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.
$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.
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.
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).
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).
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.
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.
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":
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.
$jid is the bound jabber id.
$con->reg_cb (error => sub { warn "xmpp error: " . $_[1]->string . "\n" });
Basically this event is a collect event for all other error events.
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.
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.
$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.
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.
See also the event "debug_send".
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).
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');
If you want to overtake the handling of the stanza, see "iq_xml" below.
If you want to overtake the handling of the stanza, see "iq_xml" below.
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.
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.
$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
};
});
$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.
$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.
Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
melo - minor fixes
Copyright 2007, 2008 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.
| 2022-12-06 | perl v5.36.0 |