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(...);
21 my $Roster = new Net::XMPP::Roster(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
68 the 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(connection=>object) - This creates and initializes the Roster
95 object. The connection object is required
96 so that the Roster can interact with the
97 main connection object. It needs to be an
98 object that inherits from
99 Net::XMPP::Connection.
100 clear() - removes everything from the database.
102 exists(jid) - return 1 if the JID exists in the database, undef
104 otherwise. The jid can either be a string, or a
105 Net::XMPP::JID object.
106 groupExists(group) - return 1 if the group exists in the database,
108 undef otherwise.
109 groups() - returns a list of all of the roster groups.
111 jids([type, - returns a list of all of the matching JIDs. The valid
113 [group]]) types are:
114 all - return all JIDs in the roster. (default)
116 nogroup - return all JIDs not in a roster group.
117 group - return all of the JIDs in the specified
118 roster group.
119 online(jid) - return 1 if the JID is online, undef otherwise. The
121 jid can either be a string, or a Net::XMPP::JID object.
122 query(jid, - return a hash representing all of the data in the
124 [key]) DB for this JID. The jid can either be a string,
125 or a Net::XMPP::JID object. If you specify a key,
126 then only the value for that key is returned.
127 resource(jid) - return the string representing the resource with the
129 highest priority for the JID. The jid can either be
130 a string, or a Net::XMPP::JID object.
131 resourceQuery(jid, - return a hash representing all of the data
133 resource, the DB for the resource for this JID. The
134 [key]) jid can either be a string, or a
135 Net::XMPP::JID object. If you specify a
136 key, then only the value for that key is
137 returned.
138 resources(jid) - returns the list of resources for the JID in order
140 of highest priority to lowest priority. The jid can
141 either be a string, or a Net::XMPP::JID object.
142 resourceStore(jid, - store the specified value in the DB under
144 resource, the specified key for the resource for this
145 key, JID. The jid can either be a string, or a
146 value) Net::XMPP::JID object.
147 store(jid, - store the specified value in the DB under the
149 key, specified key for this JID. The jid can either
150 value) be a string, or a Net::XMPP::JID object.
151 Advanced Functions
153 add(jid, - Manually adds the JID to the Roster with the
154 ask=>string, specified roster item settings. This does
155 not
156 groups=>arrayref handle subscribing to other users, only
157 name=>string, manipulating the Roster object. The jid
158 subscription=>string) can either be a string or a Net::XMPP::JID.
159 addResource(jid, - Manually add the resource to the JID in
161 the
162 resource, Roster with the specified presence
163 settings.
164 priority=>int, This does not handle subscribing to other
165 show=>string, users, only manipulating the Roster
166 object.
167 status=>string) The jid can either be a string or a
168 Net::XMPP::JID.
169 remove(jid) - Removes all reference to the JID from the Roster object.
171 The jid can either be a string or a Net::XMPP::JID.
172 removeResource(jid, - Removes the resource from the jid in the
174 resource) Roster object. The jid can either be a
175 string
176 or a Net::XMPP::JID.
177 handler(packet) - Take either a Net::XMPP::IQ or Net::XMPP::Presence
179 packet and parse them according to the rules of the
180 Roster object. Note, that it will only waste CPU
181 time
182 if you pass in IQs or Presences that are not roster
183 related.
184
186 Ryan Eatmon
187
189 This module is free software, you can redistribute it and/or modify it
190 under the LGPL.
191perl v5.10.1 2010-11-12 Net::XMPP::Roster(3)