Provided by: libnet-xmpp-perl_1.05-2_all bug

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 = 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 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

       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 LGPL 2.1.