AnyEven...:Roster(3)

💜 AnyEvent::XMPP::IM::Roster(3) — the roster page, bestie edition

okay so this is the manual page for AnyEvent::XMPP::IM::Roster (that's the section 3 one, from the User Contributed Perl Documentation, iykyk) ✨

---

🌸 NAME 🌸

AnyEvent::XMPP::IM::Roster — the instant messaging roster for XMPP, aka the whole friend-list situation 💅

---

🦋 SYNOPSIS 🦋

my $con = AnyEvent::XMPP::IM::Connection->new (...);
...
my $ro  = $con->roster;
if (my $c = $ro->get_contact ('test@example.com')) {
   $c->make_message ()->add_body ("Hello there!")->send;
}

like, that's the whole vibe. get the roster, grab a contact, send a message. slay 🎀

---

✨ DESCRIPTION ✨

This module is a class for roster objects, and a roster object is the thing that holds your contact info. it's giving main character energy for your buddy list 👑

It manages the roster of a JID that's connected through an AnyEvent::XMPP::IM::Connection. it also manages the presence information that comes in, so it's lowkey doing two jobs and honestly? iconic.

You get the roster by calling the "roster" method on an AnyEvent::XMPP::IM::Connection object. There is no other way. that's it, that's the door, no side entrance 🙈

---

💖 METHODS 💖

is_retrieved

Returns true if this roster was fetched from the server, and false if this roster hasn't been retrieved yet. simple as that, no cap ⭐

new_contact ($jid, $name, $groups, $cb)

This method sends a roster item creation request to the server. $jid is the JID of the contact. $name is the nickname of the contact, and it can be undef (no nickname era, we respect it). $groups should be an array reference containing the groups this contact should be in 🫶

The callback in $cb will be called when the creation is finished. The first argument will be the "AnyEvent::XMPP::IM::Contact" object if no error occured. The second argument will be an AnyEvent::XMPP::Error::IQ object if the request resulted in an error. errors happen, we deal 💀

⚠️ Please note that the contact you are given in that callback might not yet be on the roster ("is_on_roster" still returns a false value), if the server did send the roster push after the iq result of the roster set, so don't rely on the fact that the contact is on the roster. fr fr, do not build your whole app on that assumption, bestie 😭

delete_contact ($jid, $cb)

This method will send a request to the server to delete this contact from the roster. It will result in cancelling all subscriptions — like, all of them, gone, bye 👋

$cb will be called when the request was finished. The first argument to the callback might be a AnyEvent::XMPP::Error::IQ object if the request resulted in an error.

get_contact ($jid)

Returns the contact on the roster with the JID $jid. (If $jid is not bare, the resource part will be stripped before searching — it handles the trimming for you, so thoughtful ✨)

⚠️ NOTE: This method will also return contacts that we have only presence for. To be sure the contact is on the users roster you need to call the "is_on_roster" method on the contact. so like, vibe check your contact before you trust it 👀

The return value is an instance of AnyEvent::XMPP::IM::Contact.

get_contacts

Returns the contacts that are on this roster as AnyEvent::XMPP::IM::Contact objects 🎀

⚠️ NOTE: This method only returns the contacts that have a roster item. If you haven't retrieved the roster yet the presence information is still stored, but you have to get the contacts without a roster item with the "get_contacts_off_roster" method. See below. yes, below below, keep scrolling 💅

get_contacts_off_roster

Returns the contacts that are not on the roster but for which we have received presence. Return value is a list of AnyEvent::XMPP::IM::Contact objects. these are the "we've met but we're not officially friends" contacts, we all have them 🦋

See also documentation of "get_contacts" method of AnyEvent::XMPP::IM::Roster above. (yes it's a little circular, it's fine, it's cute) 💜

get_own_contact

This method returns a AnyEvent::XMPP::IM::Contact object which stands for ourself. It will be used to keep track of our own presences. main character literally ⭐👑

debug_dump

This prints the roster and all it's contacts and their presences. for when you need to see everything at once, no filter, full dump energy 🔥

---

🌈 AUTHOR 🌈

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

---

🍓 SEE ALSO 🍓

AnyEvent::XMPP::IM::Connection, AnyEvent::XMPP::IM::Contact, AnyEvent::XMPP::IM::Presence — go read these next, they're the rest of the lore 📚

---

🧊 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 page!! this one's perl v5.42.2, dated 2026-02-15, from the AnyEven...:Roster(3) zone — go forth and manage your roster, bestie, and remember: is_on_roster before you trust 💖✨