1Net::XMPP::Roster(3pm)User Contributed Perl DocumentationNet::XMPP::Roster(3pm)
2
6 Net::XMPP::Roster - XMPP Roster Object
7
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
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 Basic Functions
20 my $Client = Net::XMPP::Client->new(...);
21 my $Roster = Net::XMPP::Roster->new(connection=>$Client);
23 or
24 my $Roster = $Client->Roster();
25 $Roster->clear();
27 if ($Roster->exists('bob@jabber.org')) { ... }
29 if ($Roster->exists(Net::XMPP::JID)) { ... }
30 if ($Roster->groupExists("Friends")) { ... }
32 my @groups = $Roster->groups();
34 my @jids = $Roster->jids();
36 my @friends = $Roster->jids("group","Friends");
37 my @unfiled = $Roster->jids("nogroup");
38 if ($Roster->online('bob@jabber.org')) { ... }
40 if ($Roster->online(Net::XMPP::JID)) { ... }
41 my %hash = $Roster->query('bob@jabber.org');
43 my %hash = $Roster->query(Net::XMPP::JID);
44 my $name = $Roster->query('bob@jabber.org',"name");
46 my $ask = $Roster->query(Net::XMPP::JID,"ask");
47 my $resource = $Roster->resource('bob@jabber.org');
49 my $resource = $Roster->resource(Net::XMPP::JID);
50 my %hash = $Roster->resourceQuery('bob@jabber.org',"Home");
52 my %hash = $Roster->resourceQuery(Net::XMPP::JID,"Club");
53 my $show = $Roster->resourceQuery('bob@jabber.org',"Home","show");
55 my $status = $Roster->resourceQuery(Net::XMPP::JID,"Work","status");
56 my @resource = $Roster->resources('bob@jabber.org');
58 my @resource = $Roster->resources(Net::XMPP::JID);
59 $Roster->resourceStore('bob@jabber.org',"Home","gpgkey",key);
61 $Roster->resourceStore(Net::XMPP::JID,"logged on","2004/04/07 ...");
62 $Roster->store('bob@jabber.org',"avatar",avatar);
64 $Roster->store(Net::XMPP::JID,"display_name","Bob");
65 Advanced Functions
67 These functions are only needed if you want to manually control the
68 Roster.
69 $Roster->add('bob@jabber.org',
71 name=>"Bob",
72 groups=>["Friends"]
73 );
74 $Roster->add(Net::XMPP::JID);
75 $Roster->addResource('bob@jabber.org',
77 "Home",
78 show=>"dnd",
79 status=>"Working"
80 );
81 $Roster->addResource(Net::XMPP::JID,"Work");
82 $Roster->remove('bob@jabber.org');
84 $Roster->remove(Net::XMPP::JID);
85 $Roster->removeResource('bob@jabber.org',"Home");
87 $Roster->removeResource(Net::XMPP::JID,"Work");
88 $Roster->handler(Net::XMPP::IQ);
90 $Roster->handler(Net::XMPP::Presence);
91
93 Basic Functions
94 new
95 new(connection=>object)
96 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 clear
103 clear()
104 removes everything from the database.
106 exists
108 exists(jid)
109 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 groupExists
114 groupExists(group)
115 return 1 if the group exists in the database, undef otherwise.
117 groups
119 groups()
120 Returns a list of all of the roster groups.
122 jids
124 jids([type, [group]])
125 returns a list of all of the matching JIDs. The valid types are:
127 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 online
134 online(jid)
135 return 1 if the JID is online, undef otherwise. The jid can either
137 be a string, or a Net::XMPP::JID object.
138 query
140 query(jid, [key])
141 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 resource
147 resource(jid)
148 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 resourceQuery
154 resourceQuery(jid,
155 resource,
156 [key])
157 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 resources
164 resources(jid)
165 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 resourceStore
171 resourceStore(jid,
172 resource,
173 key,
174 value)
175 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 store
181 store(jid, key, value)
182 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 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 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 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 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 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
221 Originally authored by Ryan Eatmon.
222 Previously maintained by Eric Hacker.
224 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.
230perl v5.38.0 2023-07-21 Net::XMPP::Roster(3pm)