Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
AnyEvent::XMPP::Ext::VUser(Contributed Perl DocumAnyEvent::XMPP::Ext::VCard(3)

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.

perl v5.32.0			  2012-12-25	 AnyEvent::XMPP::Ext::VCard(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | VCARD STRUCTURE | EVENTS | TODO | AUTHOR | COPYRIGHT & LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=AnyEvent::XMPP::Ext::VCard&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help