1AnyEvent::XMPP::Ext::VCUasredr(3C)ontributed Perl DocumeAnntyaEtvieonnt::XMPP::Ext::VCard(3)
2
3
4

NAME

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

SYNOPSIS

9          use AnyEvent::XMPP::Ext::VCard;
10
11          my $vcard = AnyEvent::XMPP::Ext::VCard->new;
12          $con->reg_cb (
13             stream_ready => sub { $vcard->hook_on ($con) }
14          );
15
16          $vcard->retrieve ($con, 'elmex@jabber.org', sub {
17             my ($jid, $vcard, $error) = @_;
18
19             if ($error) {
20                warn "couldn't get vcard for elmex@jabber.org: " . $error->string . "\n";
21             } else {
22                print "vCard nick for elmex@jabber.org: ".$vcard->{NICKNAME}."\n";
23                print "Avatar hash for elmex@jabber.org: ".$vcard->{_avatar_hash}."\n";
24             }
25          });
26
27          $vcard->store ($con, undef, { NICKNAME => 'net-xmpp2' }, sub {
28             my ($error) = @_;
29             if ($error) {
30                warn "upload failed: " . $error->string . "\n";
31             } else {
32                print "upload successful\n";
33             }
34          });
35
36          $disco->enable_feature ($vcard->disco_feature);
37

DESCRIPTION

39       This extension handles setting and retrieval of the VCard and the VCard
40       based avatars.
41
42       For example see the test suite of AnyEvent::XMPP.
43

METHODS

45       new (%args)
46           Creates a new vcard extension.  It can take a "cache" argument,
47           which should be a tied hash which should be able to save the
48           retrieved vcards.  If no "cache" is set a internal hash will be
49           used and the vcards will be retrieved everytime the program is
50           restarted.  The keys will be the stringprepped bare JIDs of the
51           people we got a vcard from and the value will be a non-cyclic
52           hash/array datastructure representing the vcard.
53
54           About this datastructure see below at VCARD STRUCTURE.
55
56           If you want to support avatars correctly make sure you hook up the
57           connection via the "hook_on" method.
58
59       hook_on ($con, $dont_retrieve_vcard)
60           $con must be an object of the class AnyEvent::XMPP::Connection (or
61           derived).  Once the vCard extension has been hooked up on a
62           connection it will add the avatar information to all outgoing
63           presence stanzas.
64
65           IMPORTANT: You need to hook on the connection BEFORE it was
66           connected. The initial presence stanza needs to contain the
67           information that we support avatars. The vcard will automatically
68           retrieved if the session wasn't already started. Otherwise you will
69           have to retrieve the vcard manually if you hook it up after the
70           "session_ready" event was received. You can prevent the automatic
71           retrieval by giving a true value in $dont_retrieve_vcard.  However,
72           just make sure to hook up on any connection before it is connected
73           if you want to offer avatar support on it.
74
75           Best is probably to do it like this:
76
77              my $vcard = AnyEvent::XMPP::Ext::VCard->new;
78              $con->reg_cb (
79                 stream_ready => sub { $vcard->hook_on ($con) }
80              );
81
82       my_vcard ($con)
83           This method returns the vcard for the account connected by $con.
84           This only works if vcard was (successfully) retrieved. If the
85           connection was hoooked up the vcard was automatically retrieved.
86
87           Alternatively $con can also be a string reprensenting the JID of an
88           account.
89
90       cache ([$newcache])
91           See also "new" about the meaning of cache hashes.  If no argument
92           is given the current cache is returned.
93
94       store ($con, $vcard, $cb)
95           This method will store your $vcard on the connected server.  $cb is
96           called when either an error occured or the storage was successful.
97           If an error occured the first argument is not undefined and
98           contains an AnyEvent::XMPP::Error::IQ object.
99
100           $con should be a AnyEvent::XMPP::Connection or an object from some
101           derived class.
102
103           $vcard has a datastructure as described below in VCARD STRUCTURE.
104
105       retrieve ($con, $jid, $cb)
106           This method will retrieve the vCard for $jid via the connection
107           $con.  If $jid is undefined the vCard of yourself is retrieved.
108           The callback $cb is called when an error occured or the vcard was
109           retrieved.  The first argument of the callback will be the JID to
110           which the vCard belongs, the second argument is the vCard itself
111           (as described in VCARD STRUCTURE below) and the thrid argument is
112           the error, if an error occured (undef otherwise).
113

VCARD STRUCTURE

115       As there are currently no nice DOM implementations in Perl and I
116       strongly dislike the DOM API in general this module has a simple Perl
117       datastructure without cycles to represent the vCard.
118
119       First an example: A fetched vCard hash may look like this:
120
121         {
122           'URL' => ['http://www.ta-sa.org/'],
123           'ORG' => [{
124                      'ORGNAME' => 'nethype GmbH'
125                    }],
126           'N' => [{
127                    'FAMILY' => 'Redeker'
128                  }],
129           'EMAIL' => ['elmex@ta-sa.org'],
130           'BDAY' => ['1984-06-01'],
131           'FN' => ['Robin'],
132           'ADR' => [
133              {
134                HOME => undef,
135                'COUNTRY' => 'Germany'
136              },
137              {
138                 WORK => undef,
139                 COUNTRY => 'Germany',
140                 LOCALITY => 'Karlsruhe'
141              }
142           ],
143           'NICKNAME' => ['elmex'],
144           'ROLE' => ['Programmer']
145         }
146
147       The keys represent the toplevel element of a vCard, the values are
148       always array references containig one or more values for the key. If
149       the value is a hash reference again it's value will not be an array
150       reference but either undef or plain values.
151
152       The values of the toplevel keys are all array references because fields
153       like "ADR" may occur multiple times.
154
155       Consult XEP-0054 for an explanation what these fields mean or contain.
156
157       There are special fields in this structure for handling avatars:
158       "_avatar" contains the binary data for the avatar image.
159       "_avatar_hash" contains the sha1 hexencoded hash of the binary image
160       data.  "_avatar_type" contains the mime type of the avatar.
161
162       If you want to store the vcard you only have to set "_avatar" and
163       "_avatar_type" if you want to store an avatar.
164

EVENTS

166       The vcard extension will emit these events:
167

TODO

169       Implement caching, the cache stuff is just a storage hash at the
170       moment.  Or maybe drop it completly and let the application handle
171       caching.
172
173       retrieve_vcard_error => $iq_error
174           When a vCard retrieval was not successful, this event is emitted.
175           This is neccessary as some retrievals may happen automatically.
176
177       vcard => $jid, $vcard
178           Whenever a vCard is retrieved, either automatically or manually,
179           this event is emitted with the retrieved vCard.
180

AUTHOR

182       Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
183
185       Copyright 2007, 2008 Robin Redeker, all rights reserved.
186
187       This program is free software; you can redistribute it and/or modify it
188       under the same terms as Perl itself.
189
190
191
192perl v5.32.1                      2021-01-26     AnyEvent::XMPP::Ext::VCard(3)
Impressum