NAME
Net::Jabber::Data - Jabber Data Library
SYNOPSIS
Net::Jabber::Data is a companion to the Net::Jabber::XDB module. It
provides the user a simple interface to set and retrieve all
parts of a Jabber XDB Data.
DESCRIPTION
Net::Jabber::Data differs from the other Net::Jabber::* modules in that
the XMLNS of the data is split out into more submodules under
Data. For specifics on each module please view the documentation
for each Net::Jabber::Data::* module. The available modules are:
Net::Jabber::Data::Agent - Agent Namespace
Net::Jabber::Data::Agents - Supported Agents list from server
Net::Jabber::Data::Auth - Simple Client Authentication
Net::Jabber::Data::AutoUpdate - Auto-Update for clients
Net::Jabber::Data::Filter - Messaging Filter
Net::Jabber::Data::Fneg - Feature Negotiation
Net::Jabber::Data::Oob - Out of Bandwidth File Transfers
Net::Jabber::Data::Register - Registration requests
Net::Jabber::Data::Roster - Buddy List management
Net::Jabber::Data::Search - Searching User Directories
Net::Jabber::Data::Time - Client Time
Net::Jabber::Data::Version - Client Version
Each of these modules provide Net::Jabber::Data with the functions
to access the data. By using delegates and the AUTOLOAD function
the functions for each namespace is used when that namespace is
active.
To access a Data object you must create an XDB object and use the
access functions there to get to the Data. To initialize the XDB with
a Jabber <xdb/> you must pass it the XML::Parser Tree array from the
Net::Jabber::Client module. In the callback function for the xdb
you can access the data tag by doing the following:
use Net::Jabber;
sub xdbCB {
my $xdb = new Net::Jabber::XDB(@_);
my $data = $mesage->GetData();
.
.
.
}
You now have access to all of the retrieval functions available.
To create a new xdb to send to the server:
use Net::Jabber;
my $xdb = new Net::Jabber::XDB();
$data = $xdb->NewData("jabber:xdb:register");
Now you can call the creation functions for the Data as defined in the
proper namespaces. See below for the general <data/> functions, and
in each data module for those functions.
For more information about the array format being passed to the CallBack
please read the Net::Jabber::Client documentation.
Retrieval functions
$xmlns = $XDB->GetXMLNS();
$str = $XDB->GetXML();
@xdb = $XDB->GetTree();
Creation functions
$Data->SetXMLNS("jabber:xdb:roster");
METHODS
Retrieval functions
GetXMLNS() - returns a string with the namespace of the data that
the <xdb/> contains.
GetXML() - returns the XML string that represents the <xdb/>. This
is used by the Send() function in Client.pm to send
this object as a Jabber XDB.
GetTree() - returns an array that contains the <xdb/> tag in XML::Parser
Tree format.
Creation functions
SetXMLNS(string) - sets the xmlns of the <data/> to the string.
CUSTOM Data MODULES
Part of the flexability of this module is that you can write your own
module to handle a new namespace if you so choose. The SetDelegates
function is your way to register the xmlns and which module will
provide the missing access functions.
To register your namespace and module, you can either create an XDB
object and register it once, or you can use the SetDelegates
function in Client.pm to do it for you:
my $Client = new Net::Jabber::Client();
$Client->AddDelegate(namespace=>"blah:blah",
parent=>"Net::Jabber::Data",
delegate=>"Blah::Blah");
or
my $Transport = new Net::Jabber::Transport();
$Transport->AddDelegate(namespace=>"blah:blah",
parent=>"Net::Jabber::Data",
delegate=>"Blah::Blah");
Once you have the delegate registered you need to define the access
functions. Here is a an example module:
package Blah::Blah;
sub new {
my $proto = shift;
my $class = ref($proto) || $proto;
my $self = { };
$self->{VERSION} = $VERSION;
bless($self, $proto);
return $self;
}
sub SetBlah {
shift;
my $self = shift;
my ($blah) = @_;
return &Net::Jabber::SetXMLData("single",$self->{DATA},"blah","$blah",{});
}
sub GetBlah {
shift;
my $self = shift;
return &Net::Jabber::GetXMLData("value",$self->{DATA},"blah","");
}
1;
Now when you create a new Data object and call GetBlah on that object
it will AUTOLOAD the above function and handle the request.
AUTHOR
By Ryan Eatmon in May of 2000 for http://jabber.org..
COPYRIGHT
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.