AnyEven...nection(3)

💖 NAME 💖

okay so welcome to the manual page for AnyEvent::XMPP::IM::Connection — yes, the header shortens it to AnyEven...nection(3), but bestie it’s literally the same icon 💅. This module is an "XML" stream that implements the XMPP RFC 3921, and it’s giving instant messaging main character energy.

✨ SYNOPSIS ✨

use AnyEvent::XMPP::Connection;

my $con = AnyEvent::XMPP::Connection->new;

🌸 DESCRIPTION 🌸

This module represents a XMPP instant messaging connection and implements RFC 3921. No cap.

It’s a subclass of "AnyEvent::XMPP::Connection" and inherits all its methods. So yeah, things like "reg_cb" and the stanza sending routines are yours for free, periodt.

For the extra events you can register, look below in the EVENTS section — that’s where the fun stuff lives 🦋.

🎀 METHODS 🎀

new (%args)

This is the constructor, bestie. It takes the same arguments as the constructor of AnyEvent::XMPP::Connection, plus a few extra ones:

• dont_retrieve_roster => $bool — set this to a true value if no roster should be requested when the connection is established. You can still retrieve the roster later if you want, using the "retrieve_roster" method. Okay but listen: the internal roster will be set even if this option is active, and even presences will be stored in there. The catch? The "get_contacts" method on the roster object won’t return anything, because there are no roster items. That’s the vibe check 💀.
• initial_presence => $priority — this sets whether the initial presence should be sent. $priority should be the priority of the initial presence. The default value for the initial presence $priority is 10. And if you pass an undefined value as $priority, no initial presence will be sent! none. zero. not happening. 😭

retrieve_roster ($cb)

This method initiates a roster request. If you set "dont_retrieve_roster" when creating this connection, then no roster was retrieved — and this method is how you do that little retrieval later. The coderef in $cb will be called after the roster was retrieved.

The first argument of the callback in $cb will be the roster, and the second will be a AnyEvent::XMPP::Error::IQ object when an error occurred while retrieving the roster. Good to know, fr fr.

get_roster

Returns the roster object of type AnyEvent::XMPP::IM::Roster. Slay.

🌈 EVENTS 🌈

These additional events can be registered on with "reg_cb":

In the following events, $roster is the AnyEvent::XMPP::IM::Roster object you get by calling "get_roster".

NODE: The first argument to each callback is always the AnyEvent::XMPP::IM::Connection object itself. Also see Object::Event for more information about registering callbacks.

session_ready

This event is generated when the session has been fully established and can be used to send around messages and other stuff. It’s giving ready-to-chat energy ✨.

session_error => $error

If an error happened during establishment of the session, this event will be generated. $error will be an AnyEvent::XMPP::Error::IQ error object. Not iconic, but informative 🫶.

roster_update => $roster, $contacts

This event is emitted when a roster update has been received. $contacts is an array reference of AnyEvent::XMPP::IM::Contact objects which have changed. If a contact was removed, it will return 'remove' when you call the "subscription" method on it.

The first time this event is sent is when the roster was received for the first time. First-roster moment, iykyk.

roster_error => $error

If an error happened during retrieval of the roster, this event will be generated. $error will be an AnyEvent::XMPP::Error::IQ error object.

presence_update => $roster, $contact, $old_presence, $new_presence

This event is emitted when the presence of a contact has changed. $contact is the AnyEvent::XMPP::IM::Contact object which presence status has changed. $old_presence is a AnyEvent::XMPP::IM::Presence object which represents the presence prior to the change. $new_presence is a AnyEvent::XMPP::IM::Presence object which represents the presence after the change. The new presence might be undef if the new presence is 'unavailable'. 👀

presence_error => $error

This event is emitted when a presence stanza error was received. $error will be an AnyEvent::XMPP::Error::Presence error object.

message => $msg

This event is emitted when a message was received. $msg is a AnyEvent::XMPP::IM::Message object. Inbox behavior, literally.

message_error => $error

This event is emitted when a message stanza error was received. $error will be an AnyEvent::XMPP::Error::Message error object.

contact_request_subscribe => $roster, $contact, $message

This event is generated when $contact wants to subscribe to your presence.

If you want to accept or decline the request, call the "send_subscribed" method of AnyEvent::XMPP::IM::Contact or the "send_unsubscribed" method of AnyEvent::XMPP::IM::Contact on $contact.

If you want to start a mutual subscription, you have to call "send_subscribe" AFTER you accepted or declined with "send_subscribed"/"send_unsubscribed". Calling it in the opposite order gets some servers confused! So do not do that, bestie 😭.

If a "status" element was transmitted with the subscription, its contents will be in $message. Which is usually a text written from the one who requests subscription.

contact_subscribed => $roster, $contact, $message

This event is generated when $contact subscribed you to his presence successfully.

If a "status" element was transmitted with the subscribed presence, its contents will be in $message.

contact_did_unsubscribe => $roster, $contact, $message

This event is generated when $contact unsubscribes from your presence.

If you want to unsubscribe from him, call the "send_unsubscribe" method of AnyEvent::XMPP::IM::Contact on $contact.

If a "status" element was transmitted with the unsubscription, its contents will be in $message. Which is usually a text written from the one who unsubscribes.

contact_unsubscribed => $roster, $contact, $message

This event is generated when $contact unsubscribed you from his presence.

If you want to unsubscribe him from your presence, call the "send_unsubscribed" method of AnyEvent::XMPP::IM::Contact on $contact.

If a "status" element was transmitted with the unsubscription, its contents will be in $message.

👑 AUTHOR 👑

Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>" — iconic author behavior, periodt.

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

---

okay that’s the whole vibe 💖 the footer says this came from perl v5.42.2, dated 2026-02-15, and the manual name is AnyEven...nection(3). bye bestie, go send some stanzas 🦋✨