AnyEven...nection(3)

okay bestie, welcome to the friendliest manpage walkthrough you've ever had 💖 This is AnyEvent::XMPP::Connection(3) from the User Contributed Perl Documentation — yes, the header line gets all squished to AnyEven...nection(3) when your terminal is being dramatic, but it's the same page, iykyk.

✨ NAME ✨

AnyEvent::XMPP::Connection — it's the XML stream that implements the XMPP RFC 3920. That's the whole vibe: one stream, doing stream things. 🦋

🌈 SYNOPSIS 🌈

Like, here's how you actually spin one up:

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

That comment is not me being cute, that's literally in there — connect does a non-blocking connect. Periodt. 💅

🎀 DESCRIPTION 🎀

So this module represents a XMPP stream, exactly as described in RFC 3920. You can send the basic XMPP XML stanzas with methods like send_iq, send_message and send_presence — those three, that's the crew. 🫶

And you receive events with the reg_cb event framework, straight from the connection. It's giving subscribe-to-the-vibes.

If you're here for the instant messaging stuff, lowkey go look at AnyEvent::XMPP::IM::Connection instead. That's the one with the IM extras. 💖

👑 METHODS 👑

🌸 new (%args) 🌸

The constructor, bestie. You can pass these into %args:

• language => $tag — the language of the human readable contents that get transmitted over the stream. Default is 'en'. Please look in RFC 3066 to see how $tag should look, okay? 📚
• jid => $jid — sets the settings username, domain and (optionally) resource from a $jid. One string, three settings, iconic.
• username => $username — your $username, aka 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 AnyEvent::XMPP::Util for utility functions to check this. NOTE: this field has no effect if jid is given!

• domain => $domain — if you didn't provide a jid (see above 👆) you have to set the username you want to connect as (also above 👆) and the $domain to connect to.

NOTE: this field has no effect if jid is given!

• resource => $resource — if this argument is given, $resource gets passed as the 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 AnyEvent::XMPP::Util for utility functions to check this.

• host => $host — the hostname where we're going to connect. The default is the domain of the jid.

NOTE: to disable DNS SRV lookup you need to specify the port number yourself. See port below.

• use_host_as_sasl_hostname => $bool — a special parameter for people who might want to use the GSSAPI SASL mechanism. It causes the value of the host parameter (see above) to be passed to the SASL mechanisms, instead of the domain of the JID. This flag is provided until support for XEP 0233 is deployed, which will fix the hostname issue w.r.t. GSSAPI SASL. Big brain stuff. 🧚
• port => $port — optional! The default value for $port is 'xmpp-client=5222', which gets used as the $service argument to tcp_connect of AnyEvent::Socket.

NOTE: if you specify the port number here (instead of 'xmpp-client=5222'), no DNS SRV lookup will be done when connecting. That's the trap door, bestie 🚪.

• connect_timeout => $timeout — sets the connection timeout. If the socket connect takes too long, a disconnect event gets generated with an appropriate error message. If this argument is not given, no timeout is installed for the connects. 😬
• password => $password — the password for the username above. Keep it secret, keep it safe 🤫.
• disable_ssl => $bool — if $bool is true, no SSL will be used.
• old_style_ssl => $bool — if $bool is true, the TLS handshake gets initiated when the TCP connection was established. Useful if you have to connect to an old Jabber server, with old-style SSL connections on port 5223.

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. 🔥 Fr fr, be careful.

• disable_sasl => $bool — if $bool is true, SASL will NOT be used to authenticate with the server, even if it advertises SASL through stream features. Alternative authentication methods will be used instead, such as IQ Auth (XEP-0078) if the server offers it.
• disable_iq_auth => $bool — this disables the use of IQ Auth (XEP-0078) for authentication. You might want to exclude it because it's deprecated and insecure 💀. (However, the author wants to reach a maximum in compatibility with AnyEvent::XMPP, so they're not disabling this by default.)

See also disable_old_jabber_authentication below.

• anal_iq_auth => $bool — this enables the anal iq auth mechanism, which will first look in the stream features before trying to start iq authentication. Yes, servers don't always advertise what they can. 🙈 This option was only implemented for the author's test suite.
• disable_old_jabber_authentication => $bool — if $bool is a true value, then the VERY old style authentication method with VERY old jabber server won't be used when a <stream> start tag from the server without version attribute is received. 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. 😭

• stream_version_override => $version — ⚠️ NOTE: only use if you really know what you are doing! This will override the stream version which is sent in the XMPP stream initiation element. It's currently only used by the tests which set $version to '0.9' for testing IQ authentication with ejabberd.
• whitespace_ping_interval => $interval — sets the whitespace ping interval, in seconds. The default interval is 60 seconds. You can disable the whitespace ping by setting $interval to 0. 🕐

---

🦋 connect () 🦋

Tries to connect (non blocking!) to the domain and port you passed in new.

The connection is performed non blocking, so this method will just trigger the connection process — it does not sit there waiting, it's got main character energy and moves on. The connect event 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 an AnyEvent::XMPP::Connection object. You need to recreate it if you want to reconnect. No take-backs, bestie.

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. Simple queen behaviour. 👑

🌟 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 an AnyEvent::XMPP::Error::IQ object, where the condition method returns a special value (see also the 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. Slay.

If you want to respond to an 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. Don't try to be clever and do it another way, okay? 🙈

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 an 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 an 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. Peek at the future, lowkey iconic.

🌈 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 of $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. Easy. ✨

🌸 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'. Those five, memorize them 🫶.

$error is one of the defined error conditions described in the 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. Same deal as above, bestie 💖.

🧚 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) 💌

Okay so this one yeets a presence stanza out into the world ✨ — and for what $type, $create_cb and %attrs actually mean, go peek at the docs for the "send_presence" method of AnyEvent::XMPP::Writer. That's the source of truth bestie, I'm not gonna reinvent it 💅

The extra little glow-up here: this method does attach an id attribute to the presence stanza, and it returns the id that was used — so you can match up any possible replies later. Cute, right? 🎀

---

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

Same energy, different stanza: this sends a message stanza 📨 and for the meanings of $to, $type, $create_cb and %attrs, pls consult the docs for the "send_message" method of AnyEvent::XMPP::Writer. iykyk 🫶

And again with the id magic: this method does attach an id attribute to the message stanza and will return the id that was used, so you can react to possible replies. Obsessed with the consistency ngl 😌✨

---

do_rebind ($resource) 🔁

So picture this: you got a "bind_error" event 😭 and you're like "bestie I want to try again". That's literally what this is for — call it to set a new $resource and retry the binding. Iconic second-chance energy 🦋

If it fails again? You can call this again. But—

⚠️ Becareful not to end up in a loop! ⚠️ — like, genuinely, do not trap yourself in an infinite rebind spiral, that's giving main character who never learns 💀

And if the binding does work out, the "stream_ready" event gets generated 🎉 slay.

---

jid 🪪

After the stream has been bound to a resource, you can grab the JID via this method. That's it, that's the whole vibe ✨

---

features 🌸

Returns the last received <features> tag, in the form of an AnyEvent::XMPP::Node object. Little snapshot of what the server's offering, love that for you 💖

---

stream_id 🔑

This is the ID of this stream that was given to us by the server. No cap, that's the one 👑

✨ EVENTS ✨

okay so first things first: AnyEvent::XMPP::Connection is derived from the Object::Event class, so it inherits that whole event-callback-registering situation from it. Consult the documentation of Object::Event for more details, bestie 💅

NODE: every callback gets the AnyEvent::XMPP::Connection object as its first argument. The further callback arguments are described in the following listing of events.

These events can be registered on with reg_cb:

• stream_features => $node — sent when a stream feature (<features>) tag is received. $node is the AnyEvent::XMPP::Node object that represents the <features> tag ✨
• stream_pre_authentication — 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 a true value, the authentication continues. If it is undef or a false value, authentication is stopped and you need to call authentication later. (The original page has a stray value right there; we’re not fixing it, that’s part of the lore 💀)

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

• stream_ready => $jid — 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 — 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 — sent if a XML stream error occured. $error is a AnyEvent::XMPP::Error::Stream object 🍓
• xml_parser_error => $error — generated whenever the parser trips over XML that it can't read. $error is a AnyEvent::XMPP::Error::Parser object 🧚
• tls_error — emitted when a TLS error occured on TLS negotiation. After this the connection will be disconnected. No cap, it’s done after that 💀
• sasl_error => $error — emitted on SASL authentication error.
• iq_auth_error => $error — emitted when IQ authentication (XEP-0078) failed.
• bind_error => $error, $resource — 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. iconic chaotic dev energy, honestly 🙈

• connect => $host, $port — 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 — 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 — 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 — 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 — invoked whenever data is written out. This event is mostly the same as send_stanza_data 💅
• debug_recv => $data — 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 — 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 — 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 — 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 💖

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

🌸 CONTRIBUTORS 🌸

melo - minor fixes 🎀

👑 COPYRIGHT & LICENSE 👑

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 ✨

---

bestie, this iconic page is brought to you by perl v5.42.2, dated 2026-02-15 — mwah 💋