AnyEven...::VCard(3)

📦
version 0.55 · 7 versions
, in alpine 3.24

Hey bestie 💖 welcome to the AnyEven...::VCard(3) page from User Contributed Perl Documentation — this one is all about AnyEvent::XMPP::Ext::VCard, aka VCards (XEP-0054 & XEP-0084). It’s giving XMPP glow-up energy, and we’re gonna get through every detail together 🫶✨

✨ NAME ✨

AnyEvent::XMPP::Ext::VCard - VCards (XEP-0054 & XEP-0084)

🚀 SYNOPSIS 🚀

use AnyEvent::XMPP::Ext::VCard;

my $vcard = AnyEvent::XMPP::Ext::VCard->new;
$con->reg_cb (
   stream_ready => sub { $vcard->hook_on ($con) }
);

$vcard->retrieve ($con, 'elmex@jabber.org', sub {
   my ($jid, $vcard, $error) = @_;

   if ($error) {
      warn "couldn't get vcard for elmex@jabber.org: " . $error->string . "\n";
   } else {
      print "vCard nick for elmex@jabber.org: ".$vcard->{NICKNAME}."\n";
      print "Avatar hash for elmex@jabber.org: ".$vcard->{_avatar_hash}."\n";
   }
});

$vcard->store ($con, undef, { NICKNAME => 'net-xmpp2' }, sub {
   my ($error) = @_;
   if ($error) {
      warn "upload failed: " . $error->string . "\n";
   } else {
      print "upload successful\n";
   }
});

$disco->enable_feature ($vcard->disco_feature);

💖 DESCRIPTION 💖

This extension handles setting and retrieval of the VCard and the VCard based avatars. Iconic behavior, honestly.

For example, go peek at the test suite of AnyEvent::XMPP — that’s where the real demo energy lives 👀✨

🛠 METHODS 🛠

💫 new (%args) 💫

Creates a new vcard extension. It can take a cache argument, which should be a tied hash that should be able to save the retrieved vcards. If no cache is set, an internal hash will be used and the vcards will be retrieved every time the program is restarted 😭 (no cap, that’s the default).

The keys will be the stringprepped bare JIDs of the people we got a vcard from, and the value will be a non-cyclic hash/array datastructure representing the vcard.

About this datastructure, see below at VCARD STRUCTURE — it’s got lore 🧚

If you want to support avatars correctly, make sure you hook up the connection via the hook_on method. Periodt.

🪝 hook_on ($con, $dont_retrieve_vcard) 🪝

$con must be an object of the class AnyEvent::XMPP::Connection (or derived). Once the vCard extension has been hooked up on a connection, it will add the avatar information to all outgoing presence stanzas. Slay 💅

IMPORTANT: You need to hook on the connection BEFORE it was connected. The initial presence stanza needs to contain the information that we support avatars. The vcard will automatically retrieved if the session wasn’t already started. Otherwise you will have to retrieve the vcard manually if you hook it up after the session_ready event was received. You can prevent the automatic retrieval by giving a true value in $dont_retrieve_vcard. However, just make sure to hook up on any connection before it is connected if you want to offer avatar support on it. This is one of those “read it twice, bestie” moments 😭💖

Best is probably to do it like this:

my $vcard = AnyEvent::XMPP::Ext::VCard->new;
$con->reg_cb (
   stream_ready => sub { $vcard->hook_on ($con) }
);

🪞 my_vcard ($con) 🪞

This method returns the vcard for the account connected by $con. This only works if vcard was (successfully) retrieved. If the connection was hoooked up, the vcard was automatically retrieved.

Alternatively $con can also be a string reprensenting the JID of an account. Lowkey handy 🫶

🗂️ cache ([$newcache]) 🗂️

See also new about the meaning of cache hashes. If no argument is given, the current cache is returned. That’s it, that’s the method ✨

💾 store ($con, $vcard, $cb) 💾

This method will store your $vcard on the connected server. $cb is called when either an error occured or the storage was successful. If an error occured, the first argument is not undefined and contains an AnyEvent::XMPP::Error::IQ object.

$con should be a AnyEvent::XMPP::Connection or an object from some derived class.

$vcard has a datastructure as described below in VCARD STRUCTURE.

🔎 retrieve ($con, $jid, $cb) 🔎

This method will retrieve the vCard for $jid via the connection $con. If $jid is undefined, the vCard of yourself is retrieved. The callback $cb is called when an error occured or the vcard was retrieved. The first argument of the callback will be the JID to which the vCard belongs, the second argument is the vCard itself (as described in VCARD STRUCTURE below), and the thrid argument is the error, if an error occured (undef otherwise).

🧬 VCARD STRUCTURE 🧬

As there are currently no nice DOM implementations in Perl and I strongly dislike the DOM API in general, this module has a simple Perl datastructure without cycles to represent the vCard. We love a pragmatic icon 💅

First, an example: a fetched vCard hash may look like this:

{
  'URL' => ['http://www.ta-sa.org/'],
  'ORG' => [{
             'ORGNAME' => 'nethype GmbH'
           }],
  'N' => [{
           'FAMILY' => 'Redeker'
         }],
  'EMAIL' => ['elmex@ta-sa.org'],
  'BDAY' => ['1984-06-01'],
  'FN' => ['Robin'],
  'ADR' => [
     {
       HOME => undef,
       'COUNTRY' => 'Germany'
     },
     {
        WORK => undef,
        COUNTRY => 'Germany',
        LOCALITY => 'Karlsruhe'
     }
  ],
  'NICKNAME' => ['elmex'],
  'ROLE' => ['Programmer']
}

The keys represent the toplevel element of a vCard, and the values are always array references containing one or more values for the key. If the value is a hash reference again, its value will not be an array reference but either undef or plain values.

The values of the toplevel keys are all array references because fields like ADR may occur multiple times.

Consult XEP-0054 for an explanation of what these fields mean or contain. It’s giving documentation-with-lore 🌈

There are special fields in this structure for handling avatars:

  • _avatar contains the binary data for the avatar image.
  • _avatar_hash contains the sha1 hexencoded hash of the binary image data.
  • _avatar_type contains the mime type of the avatar.

If you want to store the vcard, you only have to set _avatar and _avatar_type if you want to store an avatar. Easy peasy 🍓

📣 EVENTS 📣

The vcard extension will emit these events:

📝 TODO 📝

Implement caching, the cache stuff is just a storage hash at the moment. Or maybe drop it completly and let the application handle caching. Honestly? Mood. That’s the whole TODO note 😭✨

  • retrieve_vcard_error => $iq_error — When a vCard retrieval was not successful, this event is emitted. This is neccessary as some retrievals may happen automatically.
  • vcard => $jid, $vcard — Whenever a vCard is retrieved, either automatically or manually, this event is emitted with the retrieved vCard.

👑 AUTHOR 👑

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

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.

Signing off bestie: this is AnyEven...::VCard(3) from perl v5.42.2, dated 2026-02-15 💖🫶✨

📦 where this page comes from