Net::XMPP::Roster - phpMan

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 AT 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 AT jabber.org')) { ... }
      if ($Roster->online(Net::XMPP::JID)) { ... }

      my %hash = $Roster->query('bob AT jabber.org');
      my %hash = $Roster->query(Net::XMPP::JID);

      my $name = $Roster->query('bob AT jabber.org',"name");
      my $ask  = $Roster->query(Net::XMPP::JID,"ask");

      my $resource = $Roster->resource('bob AT jabber.org');
      my $resource = $Roster->resource(Net::XMPP::JID);

      my %hash = $Roster->resourceQuery('bob AT jabber.org',"Home");
      my %hash = $Roster->resourceQuery(Net::XMPP::JID,"Club");

      my $show   = $Roster->resourceQuery('bob AT jabber.org',"Home","show");
      my $status = $Roster->resourceQuery(Net::XMPP::JID,"Work","status");

      my @resource = $Roster->resources('bob AT jabber.org');
      my @resource = $Roster->resources(Net::XMPP::JID);

      $Roster->resourceStore('bob AT jabber.org',"Home","gpgkey",key);
      $Roster->resourceStore(Net::XMPP::JID,"logged on","2004/04/07 ...");

      $Roster->store('bob AT 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 AT jabber.org',
                   name=>"Bob",
                   groups=>["Friends"]
                  );
      $Roster->add(Net::XMPP::JID);

      $Roster->addResource('bob AT jabber.org',
                           "Home",
                           show=>"dnd",
                           status=>"Working"
                          );
      $Roster->addResource(Net::XMPP::JID,"Work");

      $Roster->remove('bob AT jabber.org');
      $Roster->remove(Net::XMPP::JID);

      $Roster->removeResource('bob AT 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.