net::xmpp::jid(3) [suse man page]

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

NAME

       Net::XMPP::JID - XMPP JID Module

SYNOPSIS

	 Net::XMPP::JID is a companion to the Net::XMPP module.
	 It provides the user a simple interface to set and retrieve all
	 parts of a Jabber ID (userid on a server).

DESCRIPTION

	 To initialize the JID you must pass it the string that represents the
	 jid from the XML packet.  Inside the XMPP modules this is done
	 automatically and the JID object is returned instead of a string.
	 For example, in the callback function for the XMPP object foo:

	   use Net::XMPP;

	   sub foo {
	     my $foo = new Net::XMPP::Foo(@_);
	     my $from = $foo->GetFrom();
	     my $JID = new Net::XMPP::JID($from);
	     .
	     .
	     .
	   }

	 You now have access to all of the retrieval functions available.

	 To create a new JID to send to the server:

	   use Net::XMPP;

	   $JID = new Net::XMPP::JID();

	 Now you can call the creation functions below to populate the tag
	 before sending it.

   Retrieval functions
	   $userid   = $JID->GetUserID();
	   $server   = $JID->GetServer();
	   $resource = $JID->GetResource();

	   $JID      = $JID->GetJID();
	   $fullJID  = $JID->GetJID("full");
	   $baseJID  = $JID->GetJID("base");

   Creation functions
	   $JID->SetJID(userid=>"bob",
			server=>"jabber.org",
			resource=>"Work");

	   $JID->SetJID('blue@moon.org/Home');

	   $JID->SetUserID("foo");
	   $JID->SetServer("bar.net");
	   $JID->SetResource("Foo Bar");

METHODS

   Retrieval functions
	 GetUserID() - returns a string with the userid of the JID.
		       If the string is an address (bob%jabber.org) then
		       the function will return it as an address
		       (bob@jabber.org).

	 GetServer() - returns a string with the server of the JID.

	 GetResource() - returns a string with the resource of the JID.

	 GetJID()	- returns a string that represents the JID stored
	 GetJID("full")   within.  If the "full" string is specified, then
	 GetJID("base")   you get the full JID, including Resource, which
			  should be used to send to the server.  If the "base",
			  string is specified, then you will just get
			  user@server, or the base JID.

   Creation functions
	 SetJID(userid=>string,   - set multiple fields in the jid at
		server=>string,     one time.  This is a cumulative
		resource=>string)   and over writing action.  If you set
	 SetJID(string) 	    the "userid" attribute twice, the second
				    setting is what is used.  If you set
				    the server, and then set the resource
				    then both will be in the jid.  If all
				    you pass is a string, then that string
				    is used as the JID.  For valid settings
				    read the specific Set functions below.

	 SetUserID(string) - sets the userid.  Must be a valid userid or the
			     server will complain if you try to use this JID
			     to talk to the server.  If the string is an
			     address then it will be converted to the %
			     form suitable for using as a User ID.

	 SetServer(string) - sets the server.  Must be a valid host on the
			     network or the server will not be able to talk
			     to it.

	 SetResource(string) - sets the resource of the userid to talk to.

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::JID(3)

Net::XMPP::Roster(3pm)					User Contributed Perl Documentation				    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.

perl v5.14.2							    2012-11-06						    Net::XMPP::Roster(3pm)