1AnyEvent::XMPP::IM::ConUtsaecrt(C3o)ntributed Perl DocumAennytEavteinotn::XMPP::IM::Contact(3)
2
3
4
6 AnyEvent::XMPP::IM::Contact - Instant messaging roster contact
7
9 my $con = AnyEvent::XMPP::IM::Connection->new (...);
10 ...
11 my $ro = $con->roster;
12 if (my $c = $ro->get_contact ('test@example.com')) {
13 $c->make_message ()->add_body ("Hello there!")->send;
14 }
15
17 This module represents a class for contact objects which populate a
18 roster (AnyEvent::XMPP::IM::Roster.
19
20 There are two types of 'contacts' that are managed by this class. The
21 first are contacts that are on the users roster, and the second are
22 contacts that are not on the users roster.
23
24 To find our whether this is a contact which is actually available as
25 roster item in the users roster, you should consult the "is_on_roster"
26 method (see below).
27
28 Another special kind of contact is the contact which stands for ourself
29 and is mostly only used for keeping track of our own presences and
30 resources. But note that even if the "is_me" method returns true, the
31 "is_on_roster" method might also return a true value, in case we have a
32 roster item of ourself on the roster (which might happen in rare cases
33 :).
34
35 You can get an instance of this class only by calling the "get_contact"
36 function on a roster object.
37
39 send_update ($cb, %upd)
40 This method updates a contact. If the request is finished it will
41 call $cb. If it resulted in an error the first argument of that
42 callback will be a AnyEvent::XMPP::Error::IQ object.
43
44 The %upd hash should have one of the following keys and defines
45 what parts of the contact to update:
46
47 name => $name
48 Updates the name of the contact. $name = '' erases the contact.
49
50 add_group => $groups
51 Adds the contact to the groups in the array reference $groups.
52
53 remove_group => $groups
54 Removes the contact from the groups in the array reference
55 $groups.
56
57 groups => $groups
58 This sets the groups of the contact. $groups should be an array
59 reference of the groups.
60
61 send_subscribe ()
62 This method sends this contact a subscription request.
63
64 send_subscribed ()
65 This method accepts a contact's subscription request.
66
67 send_unsubscribe ()
68 This method sends this contact a unsubscription request.
69
70 send_unsubscribed ()
71 This method sends this contact a unsubscription request which
72 unsubscribes ones own presence from him (he wont get any further
73 presence from us).
74
75 update ($item)
76 This method wants a AnyEvent::XMPP::Node in $item which should be a
77 roster item received from the server. The method will update the
78 contact accordingly and return it self.
79
80 update_presence ($presence)
81 This method updates the presence of contacts on the roster.
82 $presence must be a AnyEvent::XMPP::Node object and should be a
83 presence packet.
84
85 get_presence ($jid)
86 This method returns a presence of this contact if it is available.
87 The return value is an instance of AnyEvent::XMPP::IM::Presence or
88 undef if no such presence exists.
89
90 get_presences
91 Returns all presences of this contact in form of
92 AnyEvent::XMPP::IM::Presence objects.
93
94 get_priority_presence
95 Returns the presence with the highest priority.
96
97 groups
98 Returns the list of groups (strings) this contact is in.
99
100 jid Returns the bare JID of this contact.
101
102 name
103 Returns the (nick)name of this contact.
104
105 is_on_roster ()
106 Returns 1 if this is a contact that is officially on the roster and
107 not just a contact we've received presence information for.
108
109 is_me
110 Returns a true value when this contacts stands for ourself and is
111 only used for receiving presences of our own resources.
112
113 subscription
114 Returns the subscription state of this contact, which can be one
115 of:
116
117 'none', 'to', 'from', 'both'
118
119 If the contact isn't on the roster anymore this method returns:
120
121 'remove'
122
123 ask Returns 'subscribe' if we asked this contact for subscription.
124
125 subscription_pending
126 Returns true if this contact has a pending subscription. That
127 means: the contact has to aknowledge the subscription.
128
129 nickname
130 Returns the nickname of this contact (or, if none is set in the
131 roster, it returns the node part of the JID)
132
133 make_message (%args)
134 This method returns a AnyEvent::XMPP::IM::Message object with the
135 to field set to this contacts JID.
136
137 %args are further arguments for the message constructor.
138
140 Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
141
143 Copyright 2007, 2008 Robin Redeker, all rights reserved.
144
145 This program is free software; you can redistribute it and/or modify it
146 under the same terms as Perl itself.
147
148
149
150perl v5.28.1 2012-12-25 AnyEvent::XMPP::IM::Contact(3)