Net::XMPP::Roster (3)

Leading comments

Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/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 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 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 = Net::XMPP::Client->new(...);

  my $Roster = Net::XMPP::Roster->new(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

  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

  clear()

removes everything from the database.

exists

  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

  groupExists(group)

return 1 if the group exists in the database, undef otherwise.

groups

  groups()

Returns a list of all of the roster groups.

jids

  jids([type, [group]])

returns a list of all of the matching JIDs. The valid 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 specified
                              roster group.

online

  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

  query(jid, [key])

return a hash representing all of the data in the

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

  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

  resourceQuery(jid,     
                resource,
                [key])

return a hash representing all of the data the

DB

for the resource 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.

resources

  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

  resourceStore(jid,     
                resource,
                key,     
                value)

store the specified value in the

DB

under the specified key for the resource for this

JID.

The jid can either be a string, or a Net::XMPP::JID object.

store

  store(jid, key, value)

store the specified value in the

DB

under the specified key for this

JID.

The jid can either be a string, or a Net::XMPP::JID object.

Advanced Functions

add(jid, - Manually adds the 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

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

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 

 time
                  if you pass in IQs or Presences that are not roster
                  related.

AUTHOR

Originally authored by Ryan Eatmon.

Previously maintained by Eric Hacker.

Currently maintained by Darian Anthony Patrick.

COPYRIGHT

This module is free software, you can redistribute it and/or modify it under the