NAME

Net::Jabber::XDB - Jabber XDB Library

SYNOPSIS

Net::Jabber::XDB is a companion to the Net::Jabber module. It
provides the user a simple interface to set and retrieve all 
parts of a Jabber XDB.

DESCRIPTION

Net::Jabber::XDB differs from the other Net::Jabber::* modules in that
the XMLNS of the data is split out into more submodules under
XDB.  For specifics on each module please view the documentation
for each Net::Jabber::Data::* module.  To see the list of avilable
namspaces and modules see Net::Jabber::Data.

To initialize the XDB with a Jabber <xdb/> you must pass it the 
XML::Parser Tree array.  For example:

  my $xdb = new Net::Jabber::XDB(@tree);

There has been a change from the old way of handling the callbacks.
You no longer have to do the above, a Net::Jabber::XDB object is passed
to the callback function for the xdb:

  use Net::Jabber;

  sub xdb {
    my ($XDB) = @_;
    .
    .
    .
  }

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

To create a new xdb to send to the server:

  use Net::Jabber;

  $XDB = new Net::Jabber::XDB();
  $XDBType = $XDB->NewData( type );
  $XDBType->SetXXXXX("yyyyy");

Now you can call the creation functions for the XDB, and for the <data/>
on the new Data object itself.  See below for the <xdb/> 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

$to       = $XDB->GetTo();
$toJID    = $XDB->GetTo("jid");
$from     = $XDB->GetFrom();
$fromJID  = $XDB->GetFrom("jid");
$type     = $XDB->GetType();

$data     = $XDB->GetData();
$dataTree = $XDB->GetDataTree();

$str      = $XDB->GetXML();
@xdb     d  = $XDB->GetTree();

Creation functions

    $XDB->SetXDB(tYpE=>"get",
		 tO=>"bob@jabber.org");

    $XDB->SetTo("bob@jabber.org");
    $XDB->SetFrom("me\@jabber.org");
    $XDB->SetType("set");

    $XDBObject = $XDB->NewData("jabber:iq:auth");
    $XDBObject = $XDB->NewData("jabber:iq:roster");

    $xdbReply = $XDB->Reply();
    $xdbReply = $XDB->Reply("client");
    $xdbReply = $XDB->Reply("transport");

Test functions

$test = $XDB->DefinedTo();
$test = $XDB->DefinedFrom();
$test = $XDB->DefinedType();

METHODS

Retrieval functions

GetTo()      - returns either a string with the Jabber Identifier,
GetTo("jid")   or a Net::Jabber::JID object for the person who is 
               going to receive the <xdb/>.  To get the JID
               object set the string to "jid", otherwise leave
               blank for the text string.

GetFrom()      -  returns either a string with the Jabber Identifier,
GetFrom("jid")    or a Net::Jabber::JID object for the person who
                  sent the <xdb/>.  To get the JID object set 
                  the string to "jid", otherwise leave blank for the 
                  text string.

GetType() - returns a string with the type <xdb/> this is.

GetData() - returns a Net::Jabber::Data object that contains the data
             in the <data/> of the <xdb/>.

GetDataTree() - returns an XML::Parser::Tree object that contains the 
                 data in the <data/> of the <xdb/>.

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

SetXDB(to=>string|JID,    - set multiple fields in the <xdb/> at one
       from=>string|JID,    time.  This is a cumulative and over
       id=>string,          writing action.  If you set the "to"
       type=>string,        attribute twice, the second setting is
       errorcode=>string,   what is used.  If you set the status, and
       error=>string)       then set the priority then both will be in
                            the <xdb/> tag.  For valid settings read the
                            specific Set functions below.

SetTo(string) - sets the to attribute.  You can either pass a string
SetTo(JID)      or a JID object.  They must be a valid Jabber 
                Identifiers or the server will return an error message.
                (ie.  jabber:bob@jabber.org, etc...)

SetFrom(string) - sets the from attribute.  You can either pass a string
SetFrom(JID)      or a JID object.  They must be a valid Jabber 
                  Identifiers or the server will return an error message.
                  (ie.  jabber:bob@jabber.org, etc...)

SetType(string) - sets the type attribute.  Valid settings are:

                  get      request information
                  set      set information
                  result   results of a get

NewData(string) - creates a new Net::Jabber::Data object with the 
                   namespace in the string.  In order for this function 
                   to work with a custom namespace, you must define and 
                   register that namespace with the XDB module.  For more 
                   information please read the documentation for 
                   Net::Jabber::Data.  NOTE: Jabber does not support
                   custom XDBs at the time of this writing.  This was just
                   including in case they do at some point.

Reply(type=>string) - creates a new XDB object and populates the to/from
                      fields.  The type will be set in the <xdb/>.

Test functions

DefinedTo() - returns 1 if the to attribute is defined in the <xdb/>, 
              0 otherwise.

DefinedFrom() - returns 1 if the from attribute is defined in the <xdb/>, 
                0 otherwise.

DefinedType() - returns 1 if the type attribute is defined in the <xdb/>, 
                0 otherwise.

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.