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.