Provided by: libnet-xmpp-perl_1.02-3_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 = 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 specified
                                     roster 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.