1AnyEvent::XMPP::IM::RosUtseerr(3C)ontributed Perl DocumeAnntyaEtvieonnt::XMPP::IM::Roster(3)
2
3
4

NAME

6       AnyEvent::XMPP::IM::Roster - Instant messaging roster for XMPP
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 roster objects which contain contact
18       information.
19
20       It manages the roster of a JID connected by an
21       AnyEvent::XMPP::IM::Connection.  It manages also the presence
22       information that is received.
23
24       You get the roster by calling the "roster" method on an
25       AnyEvent::XMPP::IM::Connection object. There is no other way.
26

METHODS

28       is_retrieved
29           Returns true if this roster was fetched from the server or false if
30           this roster hasn't been retrieved yet.
31
32       new_contact ($jid, $name, $groups, $cb)
33           This method sends a roster item creation request to the server.
34           $jid is the JID of the contact.  $name is the nickname of the
35           contact, which can be undef. $groups should be a array reference
36           containing the groups this contact should be in.
37
38           The callback in $cb will be called when the creation is finished.
39           The first argument will be the "AnyEvent::XMPP::IM::Contact" object
40           if no error occured. The second argument will be an
41           AnyEvent::XMPP::Error::IQ object if the request resulted in an
42           error.
43
44           Please note that the contact you are given in that callback might
45           not yet be on the roster ("is_on_roster" still returns a false
46           value), if the server did send the roster push after the iq result
47           of the roster set, so don't rely on the fact that the contact is on
48           the roster.
49
50       delete_contact ($jid, $cb)
51           This method will send a request to the server to delete this
52           contact from the roster. It will result in cancelling all
53           subscriptions.
54
55           $cb will be called when the request was finished. The first
56           argument to the callback might be a AnyEvent::XMPP::Error::IQ
57           object if the request resulted in an error.
58
59       get_contact ($jid)
60           Returns the contact on the roster with the JID $jid.  (If $jid is
61           not bare the resource part will be stripped before searching)
62
63           NOTE: This method will also return contacts that we have only
64           presence for. To be sure the contact is on the users roster you
65           need to call the "is_on_roster" method on the contact.
66
67           The return value is an instance of AnyEvent::XMPP::IM::Contact.
68
69       get_contacts
70           Returns the contacts that are on this roster as
71           AnyEvent::XMPP::IM::Contact objects.
72
73           NOTE: This method only returns the contacts that have a roster
74           item. If you haven't retrieved the roster yet the presence
75           information is still stored but you have to get the contacts
76           without a roster item with the "get_contacts_off_roster" method.
77           See below.
78
79       get_contacts_off_roster
80           Returns the contacts that are not on the roster but for which we
81           have received presence.  Return value is a list of
82           AnyEvent::XMPP::IM::Contact objects.
83
84           See also documentation of "get_contacts" method of
85           AnyEvent::XMPP::IM::Roster above.
86
87       get_own_contact
88           This method returns a AnyEvent::XMPP::IM::Contact object which
89           stands for ourself. It will be used to keep track of our own
90           presences.
91
92       debug_dump
93           This prints the roster and all it's contacts and their presences.
94

AUTHOR

96       Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
97

SEE ALSO

99       AnyEvent::XMPP::IM::Connection, AnyEvent::XMPP::IM::Contact,
100       AnyEvent::XMPP::IM::Presence
101

103       Copyright 2007, 2008 Robin Redeker, all rights reserved.
104
105       This program is free software; you can redistribute it and/or modify it
106       under the same terms as Perl itself.
107
108
109
110perl v5.34.0                      2021-07-22     AnyEvent::XMPP::IM::Roster(3)
Impressum