1Net::XMPP::Roster(3) User Contributed Perl Documentation Net::XMPP::Roster(3)
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
17 that it can track all roster updates, and presence packets.
18 Basic Functions
20 my $Client = new Net::XMPP::Client(...);
22 my $Roster = new Net::XMPP::Roster(connection=>$Client);
24 or
25 my $Roster = $Client->Roster();
26 $Roster->clear();
28 if ($Roster->exists('bob@jabber.org')) { ... }
30 if ($Roster->exists(Net::XMPP::JID)) { ... }
31 if ($Roster->groupExists("Friends")) { ... }
33 my @groups = $Roster->groups();
35 my @jids = $Roster->jids();
37 my @friends = $Roster->jids("group","Friends");
38 my @unfiled = $Roster->jids("nogroup");
39 if ($Roster->online('bob@jabber.org')) { ... }
41 if ($Roster->online(Net::XMPP::JID)) { ... }
42 my %hash = $Roster->query('bob@jabber.org');
44 my %hash = $Roster->query(Net::XMPP::JID);
45 my $name = $Roster->query('bob@jabber.org',"name");
47 my $ask = $Roster->query(Net::XMPP::JID,"ask");
48 my $resource = $Roster->resource('bob@jabber.org');
50 my $resource = $Roster->resource(Net::XMPP::JID);
51 my %hash = $Roster->resourceQuery('bob@jabber.org',"Home");
53 my %hash = $Roster->resourceQuery(Net::XMPP::JID,"Club");
54 my $show = $Roster->resourceQuery('bob@jabber.org',"Home","show");
56 my $status = $Roster->resourceQuery(Net::XMPP::JID,"Work","status");
57 my @resource = $Roster->resources('bob@jabber.org');
59 my @resource = $Roster->resources(Net::XMPP::JID);
60 $Roster->resourceStore('bob@jabber.org',"Home","gpgkey",key);
62 $Roster->resourceStore(Net::XMPP::JID,"logged on","2004/04/07 ...");
63 $Roster->store('bob@jabber.org',"avatar",avatar);
65 $Roster->store(Net::XMPP::JID,"display_name","Bob");
66 Advanced Functions
68 These functions are only needed if you want to manually control
70 the Roster.
71 $Roster->add('bob@jabber.org',
73 name=>"Bob",
74 groups=>["Friends"]
75 );
76 $Roster->add(Net::XMPP::JID);
77 $Roster->addResource('bob@jabber.org',
79 "Home",
80 show=>"dnd",
81 status=>"Working"
82 );
83 $Roster->addResource(Net::XMPP::JID,"Work");
84 $Roster->remove('bob@jabber.org');
86 $Roster->remove(Net::XMPP::JID);
87 $Roster->removeResource('bob@jabber.org',"Home");
89 $Roster->removeResource(Net::XMPP::JID,"Work");
90 $Roster->handler(Net::XMPP::IQ);
92 $Roster->handler(Net::XMPP::Presence);
93
95 Basic Functions
96 new(connection=>object) - This creates and initializes the Roster
98 object. The connection object is required
99 so that the Roster can interact with the
100 main connection object. It needs to be an
101 object that inherits from
102 Net::XMPP::Connection.
103 clear() - removes everything from the database.
105 exists(jid) - return 1 if the JID exists in the database, undef
107 otherwise. The jid can either be a string, or a
108 Net::XMPP::JID object.
109 groupExists(group) - return 1 if the group exists in the database,
111 undef otherwise.
112 groups() - returns a list of all of the roster groups.
114 jids([type, - returns a list of all of the matching JIDs. The valid
116 [group]]) types are:
117 all - return all JIDs in the roster. (default)
119 nogroup - return all JIDs not in a roster group.
120 group - return all of the JIDs in the specified
121 roster group.
122 online(jid) - return 1 if the JID is online, undef otherwise. The
124 jid can either be a string, or a Net::XMPP::JID object.
125 query(jid, - return a hash representing all of the data in the
127 [key]) DB for this JID. The jid can either be a string,
128 or a Net::XMPP::JID object. If you specify a key,
129 then only the value for that key is returned.
130 resource(jid) - return the string representing the resource with the
132 highest priority for the JID. The jid can either be
133 a string, or a Net::XMPP::JID object.
134 resourceQuery(jid, - return a hash representing all of the data
136 resource, the DB for the resource for this JID. The
137 [key]) jid can either be a string, or a
138 Net::XMPP::JID object. If you specify a
139 key, then only the value for that key is
140 returned.
141 resources(jid) - returns the list of resources for the JID in order
143 of highest priority to lowest priority. The jid can
144 either be a string, or a Net::XMPP::JID object.
145 resourceStore(jid, - store the specified value in the DB under
147 resource, the specified key for the resource for this
148 key, JID. The jid can either be a string, or a
149 value) Net::XMPP::JID object.
150 store(jid, - store the specified value in the DB under the
152 key, specified key for this JID. The jid can either
153 value) be a string, or a Net::XMPP::JID object.
154 Advanced Functions
156 add(jid, - Manually adds the JID to the Roster with the
158 ask=>string, specified roster item settings. This does
159 not
160 groups=>arrayref handle subscribing to other users, only
161 name=>string, manipulating the Roster object. The jid
162 subscription=>string) can either be a string or a Net::XMPP::JID.
163 addResource(jid, - Manually add the resource to the JID in
165 the
166 resource, Roster with the specified presence set‐
167 tings.
168 priority=>int, This does not handle subscribing to other
169 show=>string, users, only manipulating the Roster
170 object.
171 status=>string) The jid can either be a string or a
172 Net::XMPP::JID.
173 remove(jid) - Removes all reference to the JID from the Roster object.
175 The jid can either be a string or a Net::XMPP::JID.
176 removeResource(jid, - Removes the resource from the jid in the
178 resource) Roster object. The jid can either be a
179 string
180 or a Net::XMPP::JID.
181 handler(packet) - Take either a Net::XMPP::IQ or Net::XMPP::Presence
183 packet and parse them according to the rules of the
184 Roster object. Note, that it will only waste CPU
185 time
186 if you pass in IQs or Presences that are not roster
187 related.
188
190 Ryan Eatmon
191
193 This module is free software, you can redistribute it and/or modify it
194 under the LGPL.
195perl v5.8.8 2007-04-02 Net::XMPP::Roster(3)