view release on metacpan or  search on metacpan

lib/Net/XMPP3/Roster.pm  view on Meta::CPAN

=head1 NAME

Net::XMPP3::Roster - XMPP Roster Object

=head1 SYNOPSIS

  Net::XMPP3::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.

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

=head2 Basic Functions

  my $Client = new Net::XMPP3::Client(...);

  my $Roster = new Net::XMPP3::Roster(connection=>$Client);
    or
  my $Roster = $Client->Roster();

  $Roster->clear();

  if ($Roster->exists('bob@jabber.org')) { ... }
  if ($Roster->exists(Net::XMPP3::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::XMPP3::JID)) { ... }

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

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

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

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

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

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

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

  $Roster->store('bob@jabber.org',"avatar",avatar);
  $Roster->store(Net::XMPP3::JID,"display_name","Bob");

=head2 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::XMPP3::JID);

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

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

  $Roster->removeResource('bob@jabber.org',"Home");
  $Roster->removeResource(Net::XMPP3::JID,"Work");

  $Roster->handler(Net::XMPP3::IQ);
  $Roster->handler(Net::XMPP3::Presence);

=head1 METHODS

=head2 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::XMPP3::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::XMPP3::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.