view release on metacpan or  search on metacpan

lib/AnyEvent/XMPP/Ext/VCard.pm  view on Meta::CPAN

package AnyEvent::XMPP::Ext::VCard;
use AnyEvent::XMPP::Ext;
no warnings;
use strict;

use MIME::Base64;
use Digest::SHA qw/sha1_hex/;
use Scalar::Util;
use AnyEvent::XMPP::Namespaces qw/xmpp_ns/;
use AnyEvent::XMPP::Util qw/prep_bare_jid/;

our @ISA = qw/AnyEvent::XMPP::Ext/;

=head1 NAME

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

=head1 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);


=head1 DESCRIPTION

This extension handles setting and retrieval of the VCard and the
VCard based avatars.

For example see the test suite of L<AnyEvent::XMPP>.

=head1 METHODS

=over 4

=item B<new (%args)>

Creates a new vcard extension.
It can take a C<cache> argument, which should be a tied hash
which should be able to save the retrieved vcards.
If no C<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 B<VCARD STRUCTURE>.

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

=cut

sub new {
   my $this = shift;
   my $class = ref($this) || $this;
   my $self = bless { @_ }, $class;
   $self->init;
   $self
}

sub init {
   my ($self) = @_;

   $self->{cb_id} =
      $self->reg_cb (
         ext_before_vcard => sub {
            my ($self, $jid, $vcard) = @_;
            my $vc = $self->{cache}->{prep_bare_jid ($jid)} = $vcard;
         }
      );
}

sub disco_feature { xmpp_ns ('vcard') }

=item B<hook_on ($con, $dont_retrieve_vcard)>

C<$con> must be an object of the class L<AnyEvent::XMPP::Connection> (or derived).