1AnyEvent::XMPP::IM::ConUtsaecrt(C3o)ntributed Perl DocumAennytEavteinotn::XMPP::IM::Contact(3)
2
3
4

NAME

6       AnyEvent::XMPP::IM::Contact - Instant messaging roster contact
7

SYNOPSIS

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

DESCRIPTION

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

METHODS

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

AUTHOR

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.38.0                      2023-07-20    AnyEvent::XMPP::IM::Contact(3)
Impressum