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.

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::Query::* module.  The available modules are:

  Net::Jabber::Query::Auth      - Simple Client Authentication
  Net::Jabber::Query::Info      - Generic Info and Profile query
  Net::Jabber::Query::Register  - Registration requests
  Net::Jabber::Query::Resource  - User Resource Management
  Net::Jabber::Query::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();
$toJID     = $IQ->GetTo("jid");
$from      = $IQ->GetFrom();
$fromJID   = $IQ->GetFrom("jid");
$id        = $IQ->GetID();
$type      = $IQ->GetType();
$error     = $IQ->GetError();
$errorType = $IQ->GetErrorType();

$queryTag  = $IQ->GetQuery();
$qureyTree = $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");

    $IQ->SetIQ(to=>"bob\@jabber.org",
               errortype=>"denied",
               error=>"Permission Denied");
    $IQ->SetErrorType("denied");
    $IQ->SetError("Permission Denied");

    $IQObject = $IQ->NewQuery("jabber:iq:auth");
    $IQObject = $IQ->NewQuery("jabber:iq:roster");

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 <iq/>.  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 <iq/>.  To get the JID object set 
                  the string to "jid", otherwise leave blank for the 
                  text string.

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

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

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::Query object that contains the data
             in the <query/> of the <iq/>.

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

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|JID,    - set multiple fields in the <iq/> at one
       from=>string|JID,    time.  This is a cumulative and over
       type=>string,        writing action.  If you set the "to"
       errortype=>string,   attribute twice, the second setting is
       error=>string)       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

 SetErrorType(string) - sets the error type of the <iq/>.

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

 NewQuery(string) - creates a new Net::Jabber::Query 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 IQ module.  For more 
                    information please read the documentation for 
                    Net::Jabber::Query.  NOTE: Jabber does not support
                    custom IQs at the time of this writing.  This was just
                    including in case they do at some point.

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.