Linux Certif

Toute la documentation sur la certification Linux LPI

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