Provided by: libanyevent-xmpp-perl_0.54-2_all bug

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.

       For example see the test suite of AnyEvent::XMPP.

METHODS

       new (%args)
           Creates a new vcard extension.  It can take a "cache" argument, which should be a tied
           hash which should be able to save the retrieved vcards.  If no "cache" is set a
           internal hash will be used and the vcards will be retrieved everytime the program is
           restarted.  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.

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

       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.

           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.

           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.

       cache ([$newcache])
           See also "new" about the meaning of cache hashes.  If no argument is given the current
           cache is returned.

       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.

       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, the values are always array references
       containig one or more values for the key. If the value is a hash reference again it's
       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 what these fields mean or contain.

       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.

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.

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