1Net::XMPP::Roster(3)  User Contributed Perl Documentation Net::XMPP::Roster(3)
2
3
4

NAME

6       Net::XMPP::Roster - XMPP Roster Object
7

SYNOPSIS

9       Net::XMPP::Roster is a module that provides a developer an easy
10       interface to an XMPP roster.  It provides high level functions to
11       query, update, and manage a user's roster.
12

DESCRIPTION

14       The Roster object seeks to provide an easy to use API for interfacing
15       with a user's roster.  When you instantiate it, it automatically
16       registers with the connection to receivce the correct packets so that
17       it can track all roster updates, and presence packets.
18
19   Basic Functions
20         my $Client = Net::XMPP::Client->new(...);
21
22         my $Roster = Net::XMPP::Roster->new(connection=>$Client);
23           or
24         my $Roster = $Client->Roster();
25
26         $Roster->clear();
27
28         if ($Roster->exists('bob@jabber.org')) { ... }
29         if ($Roster->exists(Net::XMPP::JID)) { ... }
30
31         if ($Roster->groupExists("Friends")) { ... }
32
33         my @groups = $Roster->groups();
34
35         my @jids    = $Roster->jids();
36         my @friends = $Roster->jids("group","Friends");
37         my @unfiled = $Roster->jids("nogroup");
38
39         if ($Roster->online('bob@jabber.org')) { ... }
40         if ($Roster->online(Net::XMPP::JID)) { ... }
41
42         my %hash = $Roster->query('bob@jabber.org');
43         my %hash = $Roster->query(Net::XMPP::JID);
44
45         my $name = $Roster->query('bob@jabber.org',"name");
46         my $ask  = $Roster->query(Net::XMPP::JID,"ask");
47
48         my $resource = $Roster->resource('bob@jabber.org');
49         my $resource = $Roster->resource(Net::XMPP::JID);
50
51         my %hash = $Roster->resourceQuery('bob@jabber.org',"Home");
52         my %hash = $Roster->resourceQuery(Net::XMPP::JID,"Club");
53
54         my $show   = $Roster->resourceQuery('bob@jabber.org',"Home","show");
55         my $status = $Roster->resourceQuery(Net::XMPP::JID,"Work","status");
56
57         my @resource = $Roster->resources('bob@jabber.org');
58         my @resource = $Roster->resources(Net::XMPP::JID);
59
60         $Roster->resourceStore('bob@jabber.org',"Home","gpgkey",key);
61         $Roster->resourceStore(Net::XMPP::JID,"logged on","2004/04/07 ...");
62
63         $Roster->store('bob@jabber.org',"avatar",avatar);
64         $Roster->store(Net::XMPP::JID,"display_name","Bob");
65
66   Advanced Functions
67       These functions are only needed if you want to manually control the
68       Roster.
69
70         $Roster->add('bob@jabber.org',
71                      name=>"Bob",
72                      groups=>["Friends"]
73                     );
74         $Roster->add(Net::XMPP::JID);
75
76         $Roster->addResource('bob@jabber.org',
77                              "Home",
78                              show=>"dnd",
79                              status=>"Working"
80                             );
81         $Roster->addResource(Net::XMPP::JID,"Work");
82
83         $Roster->remove('bob@jabber.org');
84         $Roster->remove(Net::XMPP::JID);
85
86         $Roster->removeResource('bob@jabber.org',"Home");
87         $Roster->removeResource(Net::XMPP::JID,"Work");
88
89         $Roster->handler(Net::XMPP::IQ);
90         $Roster->handler(Net::XMPP::Presence);
91

METHODS

93   Basic Functions
94       new
95             new(connection=>object)
96
97           This creates and initializes the Roster object.  The connection
98           object is required so that the Roster can interact with the main
99           connection object.  It needs to be an object that inherits from
100           Net::XMPP::Connection.
101
102       clear
103             clear()
104
105           removes everything from the database.
106
107       exists
108             exists(jid)
109
110           return 1 if the JID exists in the database, undef otherwise.  The
111           jid can either be a string, or a Net::XMPP::JID object.
112
113       groupExists
114             groupExists(group)
115
116           return 1 if the group exists in the database, undef otherwise.
117
118       groups
119             groups()
120
121           Returns a list of all of the roster groups.
122
123       jids
124             jids([type, [group]])
125
126           returns a list of all of the matching JIDs.  The valid types are:
127
128                               all     - return all JIDs in the roster. (default)
129                               nogroup - return all JIDs not in a roster group.
130                               group   - return all of the JIDs in the specified
131                                         roster group.
132
133       online
134             online(jid)
135
136           return 1 if the JID is online, undef otherwise.  The jid can either
137           be a string, or a Net::XMPP::JID object.
138
139       query
140             query(jid, [key])
141
142           return a hash representing all of the data in the DB for this JID.
143           The jid can either be a string, or a Net::XMPP::JID object.  If you
144           specify a key, then only the value for that key is returned.
145
146       resource
147             resource(jid)
148
149           return the string representing the resource with the highest
150           priority for the JID.  The jid can either be a string, or a
151           Net::XMPP::JID object.
152
153       resourceQuery
154             resourceQuery(jid,
155                           resource,
156                           [key])
157
158           return a hash representing all of the data the DB for the resource
159           for this JID.  The jid can either be a string, or a Net::XMPP::JID
160           object.  If you specify a key, then only the value for that key is
161           returned.
162
163       resources
164             resources(jid)
165
166           returns the list of resources for the JID in order of highest
167           priority to lowest priority.  The jid can either be a string, or a
168           Net::XMPP::JID object.
169
170       resourceStore
171             resourceStore(jid,
172                           resource,
173                           key,
174                           value)
175
176           store the specified value in the DB under the specified key for the
177           resource for this JID.  The jid can either be a string, or a
178           Net::XMPP::JID object.
179
180       store
181             store(jid, key, value)
182
183           store the specified value in the DB under the specified key for
184           this JID.  The jid can either be a string, or a Net::XMPP::JID
185           object.
186
187   Advanced Functions
188       add(jid,                 - Manually adds the JID to the Roster with the
189           ask=>string,           specified roster item settings.  This does
190       not
191           groups=>arrayref       handle subscribing to other users, only
192           name=>string,          manipulating the Roster object.  The jid
193           subscription=>string)  can either be a string or a Net::XMPP::JID.
194
195       addResource(jid,            - Manually add the resource to the JID in
196       the
197                   resource,         Roster with the specified presence
198       settings.
199                   priority=>int,    This does not handle subscribing to other
200                   show=>string,     users, only manipulating the Roster
201       object.
202                   status=>string)   The jid can either be a string or a
203                                     Net::XMPP::JID.
204
205       remove(jid) - Removes all reference to the JID from the Roster object.
206                     The jid can either be a string or a Net::XMPP::JID.
207
208       removeResource(jid,      - Removes the resource from the jid in the
209                      resource)   Roster object.  The jid can either be a
210       string
211                                  or a Net::XMPP::JID.
212
213       handler(packet) - Take either a Net::XMPP::IQ or Net::XMPP::Presence
214                         packet and parse them according to the rules of the
215                         Roster object.  Note, that it will only waste CPU
216       time
217                         if you pass in IQs or Presences that are not roster
218                         related.
219

AUTHOR

221       Originally authored by Ryan Eatmon.
222
223       Previously maintained by Eric Hacker.
224
225       Currently maintained by Darian Anthony Patrick.
226
228       This module is free software, you can redistribute it and/or modify it
229       under the LGPL 2.1.
230
231
232
233perl v5.34.0                      2021-07-22              Net::XMPP::Roster(3)
Impressum