# Net::XMPP::Roster - perldoc - [phpMan]

## NAME
    [Net::XMPP::Roster](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3ARoster/markdown) - XMPP Roster Object

## SYNOPSIS
    [Net::XMPP::Roster](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3ARoster/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AClient/markdown)->new(...);

      my $Roster = [Net::XMPP::Roster](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3ARoster/markdown)->new(connection=>$Client);
        or
      my $Roster = $Client->Roster();

      $Roster->clear();

      if ($Roster->exists('<bob@jabber.org>')) { ... }
      if ($Roster->exists([Net::XMPP::JID](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown))) { ... }

      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](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown))) { ... }

      my %hash = $Roster->query('<bob@jabber.org>');
      my %hash = $Roster->query([Net::XMPP::JID](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown));

      my $name = $Roster->query('<bob@jabber.org>',"name");
      my $ask  = $Roster->query([Net::XMPP::JID](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown),"ask");

      my $resource = $Roster->resource('<bob@jabber.org>');
      my $resource = $Roster->resource([Net::XMPP::JID](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown));

      my %hash = $Roster->resourceQuery('<bob@jabber.org>',"Home");
      my %hash = $Roster->resourceQuery([Net::XMPP::JID](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown),"Club");

      my $show   = $Roster->resourceQuery('<bob@jabber.org>',"Home","show");
      my $status = $Roster->resourceQuery([Net::XMPP::JID](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown),"Work","status");

      my @resource = $Roster->resources('<bob@jabber.org>');
      my @resource = $Roster->resources([Net::XMPP::JID](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown));

      $Roster->resourceStore('<bob@jabber.org>',"Home","gpgkey",key);
      $Roster->resourceStore([Net::XMPP::JID](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown),"logged on","2004/04/07 ...");

      $Roster->store('<bob@jabber.org>',"avatar",avatar);
      $Roster->store([Net::XMPP::JID](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown),"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](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown));

      $Roster->addResource('<bob@jabber.org>',
                           "Home",
                           show=>"dnd",
                           status=>"Working"
                          );
      $Roster->addResource([Net::XMPP::JID](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown),"Work");

      $Roster->remove('<bob@jabber.org>');
      $Roster->remove([Net::XMPP::JID](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown));

      $Roster->removeResource('<bob@jabber.org>',"Home");
      $Roster->removeResource([Net::XMPP::JID](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown),"Work");

      $Roster->handler([Net::XMPP::IQ](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AIQ/markdown));
      $Roster->handler([Net::XMPP::Presence](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3APresence/markdown));

## 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](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AConnection/markdown).

    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](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown) object.

### Advanced Functions
### add
    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](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown).

### addResource
    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](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown).

### remove
    string or a [Net::XMPP::JID](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown).

### removeResource
    can either be a string or a [Net::XMPP::JID](https://www.chedong.com/phpMan.php/perldoc/Net%3A%3AXMPP%3A%3AJID/markdown).

### handler
    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.