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.