AnyEven...:Contact(3)

💖 AnyEvent::XMPP::IM::Contact(3) 💖

okay so bestie, welcome to the manual page for AnyEvent::XMPP::IM::Contact — it's a User Contributed Perl Documentation situation, from the AnyEven...:Contact(3) corner of the perl-verse, and we're about to make it make sense. 🫶

---

✨ NAME ✨

AnyEvent::XMPP::IM::Contact — like, the instant messaging roster contact class. that's the whole vibe. 💅

---

🌸 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;
}

see? grab the roster, grab the contact, send them a little "Hello there!" and you're literally done. iconic behavior. ✨

---

🦋 DESCRIPTION 🦋

So this module is a class for contact objects — y'know, the little guys that populate a roster (AnyEvent::XMPP::IM::Roster). 🎀

There are two types of 'contacts' that get managed by this class, and yes you need to know the difference:

• the first are contacts that are on the user's roster
• the second are contacts that are not on the user's roster

To find out whether a contact is actually available as a roster item in the user's roster, you should consult the "is_on_roster" method (peep it below 👀). no guessing, bestie, ask the method.

Then there's another special kind of contact: the one that stands for ourself, mostly only used for keeping track of our own presences and resources. main character energy fr fr. But — and this is important — even if the "is_me" method returns true, the "is_on_roster" method might also return a true value, in case we have a roster item of ourself on the roster (which might happen in rare cases :). so like, both can be true, it's giving nuanced.

You can only get an instance of this class by calling the "get_contact" function on a roster object. no shortcuts, that's the door. 🚪

---

💜 METHODS 💜

• send_update ($cb, %upd) — this method updates a contact. If the request is finished it will call $cb. If it resulted in an error, the first argument of that callback will be an AnyEvent::XMPP::Error::IQ object. 😭

The %upd hash should have one of the following keys, and it defines what parts of the contact to update:

• name => $name — updates the name of the contact. $name = '' erases the contact. poof. 💀
• add_group => $groups — adds the contact to the groups in the array reference $groups.
• remove_group => $groups — removes the contact from the groups in the array reference $groups.
• groups => $groups — this sets the groups of the contact. $groups should be an array reference of the groups.

• send_subscribe () — this method sends this contact a subscription request. 📨
• send_subscribed () — this method accepts a contact's subscription request. yes queen, approved. 👑
• send_unsubscribe () — this method sends this contact an unsubscription request.
• send_unsubscribed () — this method sends this contact an unsubscription request which unsubscribes one's own presence from him (he won't get any further presence from us). bye bestie, no more presence for you 🙈
• update ($item) — this method wants an AnyEvent::XMPP::Node in $item, which should be a roster item received from the server. The method will update the contact accordingly and return itself. self-returning slay ✨
• update_presence ($presence) — this method updates the presence of contacts on the roster. $presence must be an AnyEvent::XMPP::Node object and should be a presence packet.
• get_presence ($jid) — this method returns a presence of this contact if it's available. The return value is an instance of AnyEvent::XMPP::IM::Presence, or undef if no such presence exists.
• get_presences — returns all presences of this contact in the form of AnyEvent::XMPP::IM::Presence objects. the whole collection 💅
• get_priority_presence — returns the presence with the highest priority. it's giving ranking system 👑
• groups — returns the list of groups (strings) this contact is in.
• jid — returns the bare JID of this contact.
• name — returns the (nick)name of this contact.
• is_on_roster () — returns 1 if this is a contact that's officially on the roster and not just a contact we've received presence information for. official official. 🎀
• is_me — returns a true value when this contact stands for ourself and is only used for receiving presences of our own resources. it's me, hi, I'm the contact, it's me 🫶
• subscription — returns the subscription state of this contact, which can be one of:

'none', 'to', 'from', 'both'

If the contact isn't on the roster anymore, this method returns:

'remove'

• ask — returns 'subscribe' if we asked this contact for subscription.
• subscription_pending — returns true if this contact has a pending subscription. That means: the contact has to acknowledge the subscription. (the original says "aknowledge" and honestly, spelling is a vibe not a rule 💀)
• nickname — returns the nickname of this contact (or, if none is set in the roster, it returns the node part of the JID). fallback queen 👑
• make_message (%args) — this method returns an AnyEvent::XMPP::IM::Message object with the to field set to this contact's JID.

%args are further arguments for the message constructor. easy peasy 🍓

---

🌈 AUTHOR 🌈

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

---

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

---

ngl bestie, that's the whole page — every method, every option, every little undef. no cap. 🧚

and that's the tea: this was perl v5.42.2, dated 2026-02-15, and it's AnyEven...:Contact(3) signing off. mwah 💋✨