GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Net::XMPP::Roster(3) User Contributed Perl Documentation Net::XMPP::Roster(3)

Net::XMPP::Roster - XMPP Roster Object

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.

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.

  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@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");

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);

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.

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.

Originally authored by Ryan Eatmon.

Previously maintained by Eric Hacker.

Currently maintained by Darian Anthony Patrick.

This module is free software, you can redistribute it and/or modify it under the LGPL 2.1.
2022-04-07 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.