net::xmpp::roster(3pm)
NAME
Net::XMPP::Roster - XMPP Roster Object
SYNOPSIS
Net::XMPP::Roster is a module that provides a developer an easy interface to an XMPP roster. It provides high level functions to query, update, and manage a user's roster.
DESCRIPTION
- The Roster object seeks to provide an easy to use API for interfacing
with a user's roster. When you instantiate it, it automatically
registers with the connection to receivce the correct packets so
that it can track all roster updates, and presence packets. - Basic Functions
my $Client = new Net::XMPP::Client(...);- my $Roster = new Net::XMPP::Roster(connection=>$Client);
or
- my $Roster = $Client->Roster();
- $Roster->clear();
- if ($Roster->exists('bob@jabber.org')) { ... }
if ($Roster->exists(Net::XMPP::JID)) { ... } - if ($Roster->groupExists("Friends")) { ... }
- my @groups = $Roster->groups();
- my @jids = $Roster->jids();
my @friends = $Roster->jids("group","Friends");
my @unfiled = $Roster->jids("nogroup"); - if ($Roster->online('bob@jabber.org')) { ... }
if ($Roster->online(Net::XMPP::JID)) { ... } - my %hash = $Roster->query('bob@jabber.org');
my %hash = $Roster->query(Net::XMPP::JID); - my $name = $Roster->query('bob@jabber.org',"name");
my $ask = $Roster->query(Net::XMPP::JID,"ask"); - my $resource = $Roster->resource('bob@jabber.org');
my $resource = $Roster->resource(Net::XMPP::JID); - my %hash = $Roster->resourceQuery('bob@jabber.org',"Home");
my %hash = $Roster->resourceQuery(Net::XMPP::JID,"Club"); - my $show = $Roster->resourceQuery('bob@jabber.org',"Home","show");
my $status = $Roster->resourceQuery(Net::XMPP::JID,"Work","status"); - my @resource = $Roster->resources('bob@jabber.org');
my @resource = $Roster->resources(Net::XMPP::JID); - $Roster->resourceStore('bob@jabber.org',"Home","gpgkey",key);
$Roster->resourceStore(Net::XMPP::JID,"logged on","2004/04/07 ..."); - $Roster->store('bob@jabber.org',"avatar",avatar);
$Roster->store(Net::XMPP::JID,"display_name","Bob"); - Advanced Functions
These functions are only needed if you want to manually control
the Roster.- $Roster->add('bob@jabber.org',
name=>"Bob",
groups=>["Friends"] - );
- $Roster->add(Net::XMPP::JID);
- $Roster->addResource('bob@jabber.org',
- "Home",
show=>"dnd",
status=>"Working" - );
- $Roster->addResource(Net::XMPP::JID,"Work");
- $Roster->remove('bob@jabber.org');
$Roster->remove(Net::XMPP::JID); - $Roster->removeResource('bob@jabber.org',"Home");
$Roster->removeResource(Net::XMPP::JID,"Work"); - $Roster->handler(Net::XMPP::IQ);
$Roster->handler(Net::XMPP::Presence);
METHODS
- Basic Functions
- new(connection=>object) - This creates and initializes the Roster
object. The connection object is required so that the Roster can interact with the
main connection object. It needs to be an object that inherits from
Net::XMPP::Connection. - clear() - removes everything from the database.
- exists(jid) - return 1 if the JID exists in the database, undef
- otherwise. The jid can either be a string, or a
Net::XMPP::JID object. - groupExists(group) - return 1 if the group exists in the database,
- undef otherwise.
- groups() - returns a list of all of the roster groups.
- jids([type, - returns a list of all of the matching JIDs. The valid
- [group]]) types are:
all - return all JIDs in the roster. (default) nogroup - return all JIDs not in a roster group.
group - return all of the JIDs in the specifiedroster group. - online(jid) - return 1 if the JID is online, undef otherwise. The
- jid can either be a string, or a Net::XMPP::JID object.
- query(jid, - return a hash representing all of the data in the
- [key]) DB for this JID. The jid can either be a string,
or a Net::XMPP::JID object. If you specify a key,
then only the value for that key is returned. - resource(jid) - return the string representing the resource with the
- highest priority for the JID. The jid can either be a string, or a Net::XMPP::JID object.
- resourceQuery(jid, - return a hash representing all of the data
- resource, the DB for the resource for this JID. The
[key]) jid can either be a string, or a
Net::XMPP::JID object. If you specify a
key, then only the value for that key is
returned. - resources(jid) - returns the list of resources for the JID in order
- of highest priority to lowest priority. The jid can either be a string, or a Net::XMPP::JID object.
- resourceStore(jid, - store the specified value in the DB under
- resource, the specified key for the resource for this key, JID. The jid can either be a string, or a value) Net::XMPP::JID object.
- store(jid, - store the specified value in the DB under the
- key, specified key for this JID. The jid can either
value) be a string, or a Net::XMPP::JID object. - Advanced Functions
- add(jid, - Manually adds the JID to the Roster with the
- ask=>string, specified roster item settings. This does
- not
- groups=>arrayref handle subscribing to other users, only
name=>string, manipulating the Roster object. The jid
subscription=>string) can either be a string or a Net::XMPP::JID. - addResource(jid, - Manually add the resource to the JID in
the - resource, Roster with the specified presence
- settings.
- priority=>int, This does not handle subscribing to other show=>string, users, only manipulating the Roster
- object.
- status=>string) The jid can either be a string or a
Net::XMPP::JID.
- remove(jid) - Removes all reference to the JID from the Roster object.
- The jid can either be a string or a Net::XMPP::JID.
- removeResource(jid, - Removes the resource from the jid in the
- resource) Roster object. The jid can either be a
- string
- or a Net::XMPP::JID.
- handler(packet) - Take either a Net::XMPP::IQ or Net::XMPP::Presence
- packet and parse them according to the rules of the
Roster object. Note, that it will only waste CPU - time
- if you pass in IQs or Presences that are not roster
related.
AUTHOR
Ryan Eatmon
COPYRIGHT
- This module is free software, you can redistribute it and/or modify it
under the LGPL.