NAME

Net::Jabber::IQ - Jabber Info/Query Library

SYNOPSIS

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

DESCRIPTION

Net::Jabber::IQ differs from the other Net::Jabber::* modules in that
the XMLNS of the query is split out into more submodules under
IQ.  For specifics on each module please view the documentation
for each Net::Jabber::IQ::* module.  The available modules are:

  Net::Jabber::IQ::Auth      - Simple Client Authentication
  Net::Jabber::IQ::Info      - Generic Info and Profile query
  Net::Jabber::IQ::Register  - Registration requests
  Net::Jabber::IQ::Resource  - User Resource Management
  Net::Jabber::IQ::Roster    - Buddy List management

To initialize the IQ with a Jabber <iq/> you must pass it the 
XML::Parser Tree array from the Net::Jabber::Client module.  In the
callback function for the iq:

  use Net::Jabber;

  sub iq {
    my $iq = new Net::Jabber::IQ(@_);
    .
    .
    .
  }

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

To create a new iq to send to the server:

  use Net::Jabber;

  $IQ = new Net::Jabber::IQ();
  $IQType = $IQ->NewQuery( type );
  $IQType->SetXXXXX("yyyyy");

Now you can call the creation functions for the IQ, and for the <query/>
on the new Query object itself.  See below for the <iq/> functions, and
in each query 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        = $IQ->GetTo();
$from      = $IQ->GetFrom();
$id        = $IQ->GetID();
$type      = $IQ->GetType();
$xmlns     = $IQ->GetXMLNS();
$error     = $IQ->GetError();
$errorType = $IQ->GetErrorType();

$queryObj  = $IQ->GetQuery();
$tree      = $IQ->GetQueryTree();

$str       = $IQ->GetXML();
@iq        = $IQ->GetTree();

Creation functions

    $IQ->SetIQ(tYpE=>"get",
	       tO=>"bob@jabber.org",
	       query=>"info");

    $IQ->SetTo("bob@jabber.org");
    $IQ->SetType("set");

    $IQObject = $IQ->NewQuery("auth");

METHODS

Retrieval functions

GetTo() - returns a string with the Jabber Identifier of the 
          person who is going to receive the <iq/>.  <iq/>s sent
          to the server does not require a to.

GetFrom() - returns a string with the Jabber Identifier of the 
            person who sent the <iq/>.

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

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

GetXMLNS() - returns a string with the namespace of the query that
             the <iq/> contains.

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

GetErrorType() - returns a string with the type of error.

GetQuery() - returns a Net::Jabber::IQ::xxxxxx object that contains
             the data in the query.  To learn how to use this object
             please read the documentation for each 
             Net::Jabber::IQ::xxxxxx module.  These are listed at the
             top of this document.

GetQueryTree() - returns an XML::Parser tree that contains the data
                 in the query.

GetXML() - returns the XML string that represents the <iq/>. This 
           is used by the Send() function in Client.pm to send
           this object as a Jabber IQ.

GetTree() - returns an array that contains the <iq/> tag in XML::Parser 
            Tree format.

Creation functions

SetIQ(to=>string,    - set multiple fields in the <iq/> at one time.  This
      type=>string,    is a cumlative and over writing action.  If you set 
      query=>string)   the "to" attribute twice, the second setting is 
                       what is used.  If you set the status, and then set
                       the priority then both will be in the <iq/> tag.
                       For valid settings read the specific Set functions 
                       below.

SetTo(string) - sets the to attribute.  Must be a valid Jabber Identifier 
                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

NewQuery(string) - returns a Net::Jabber::IQ::xxxxxx object that contains
                   the data in the query.  The kind of object that is
                   created is based on the string that you pass to 
                   NewQuery.  Valid query types are:

                   auth        Authentication
                   info        General Information
                   register    Registrion information
                   resource    User Resource
                   roster      Buddy LIsts

AUTHOR

By Ryan Eatmon in December of 1999 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.