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

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.

perl v5.12.1							    2010-07-05						      Net::XMPP::Roster(3)