Net::Jabber::XDB - phpMan

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 available
      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 qw(Component);

        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.

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.

                     $to    = $XDB->GetTo();
                     $toJID = $XDB->GetTo("jid");

      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.

                        $from    = $XDB->GetFrom();
                        $fromJID = $XDB->GetFrom("jid");

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

                  $type = $XDB->GetType();

      GetID() - returns an integer with the id of the <xdb/>.

                $id = $XDB->GetID();

      GetAction() - returns a string with the action <xdb/> this is.

                  $action = $XDB->GetAction();

      GetMatch() - returns a string with the match <xdb/> this is.

                  $match = $XDB->GetMatch();

      GetError() - returns a string with the text description of the error.

                   $error = $XDB->GetError();

      GetErrorCode() - returns a string with the code of error.

                       $errorCode = $XDB->GetErrorCode();

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

                  $dataTag = $XDB->GetData();

      GetDataXMLNS() - returns a string with the namespace of the data
                       for this <xdb/>, if one exists.

                       $xmlns = $XDB->GetDataXMLNS();

  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
            action=>string,       what is used.  If you set the status, and
            match=>string)        then set the priority then both will be in
            errorcode=>string,    the <xdb/> tag.  For valid settings read the
            error=>string)        specific Set functions below.

                                  $XDB->SetXDB(type=>"get",
                                               to=>"bob\@jabber.org",
                                               data=>"info");

                                  $XDB->SetXDB(to=>"bob\@jabber.org",
                                               errorcode=>403,
                                               error=>"Permission Denied");

      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 AT jabber.org, etc...)

                     $XDB->SetTo("bob\@jabber.org");

      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 AT jabber.org, etc...)

                        $XDB->SetFrom("me\@jabber.org");

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

                        get      request information
                        set      set information
                        result   results of a get
                        error    there was an error

                        $XDB->SetType("set");

      SetAction(string) - sets the error code of the <xdb/>.

                          $XDB->SetAction("foo");

      SetMatch(string) - sets the error code of the <xdb/>.

                         $XDB->SetMatch("foo");

      SetErrorCode(string) - sets the error code of the <xdb/>.

                             $XDB->SetErrorCode(403);

      SetError(string) - sets the error string of the <xdb/>.

                         $XDB->SetError("Permission Denied");

      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.

                         $dataObj = $XDB->NewData("jabber:xdb:auth");
                         $dataObj = $XDB->NewData("jabber:xdb:roster");

      Reply(hash) - creates a new XDB object and populates the to/from
                    fields.  If you specify a hash the same as with SetXDB
                    then those values will override the Reply values.

                    $xdbReply = $XDB->Reply();
                    $xdbReply = $XDB->Reply(type=>"result");

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

                    $test = $XDB->DefinedTo();

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

                      $test = $XDB->DefinedFrom();

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

                    $test = $XDB->DefinedID();

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

                      $test = $XDB->DefinedType();

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

                       $test = $XDB->DefinedAction();

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

                       $test = $XDB->DefinedMatch();

      DefinedError() - returns 1 if <error/> is defined in the <xdb/>,
                       0 otherwise.

                       $test = $XDB->DefinedError();

      DefinedErrorCode() - returns 1 if the code attribute is defined in
                           <error/>, 0 otherwise.

                           $test = $XDB->DefinedErrorCode();

AUTHOR
    By Ryan Eatmon in May of 2001 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.