++ed by:

2 non-PAUSE users.

Ryan Eatmon

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.  To see the list of avilable
  namspaces and modules see Net::Jabber::Query.

  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");
    $sto        = $IQ->GetSTo();
    $stoJID     = $IQ->GetSTo("jid");
    $sfrom      = $IQ->GetSFrom();
    $sfromJID   = $IQ->GetSFrom("jid");
    $etherxTo   = $IQ->GetEtherxTo();
    $etherxFrom = $IQ->GetEtherxFrom();
    $id         = $IQ->GetID();
    $type       = $IQ->GetType();
    $error      = $IQ->GetError();
    $errorCode  = $IQ->GetErrorCode();

    $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->SetFrom("me\@jabber.org");
    $IQ->SetSTo("jabber.org");
    $IQ->SetSFrom("jabber.org");
    $IQ->SetEtherxTo("jabber.org");
    $IQ->SetEtherxFrom("transport.jabber.org");
    $IQ->SetType("set");

    $IQ->SetIQ(to=>"bob\@jabber.org",
               errorcode=>403,
               error=>"Permission Denied");
    $IQ->SetErrorCode(403);
    $IQ->SetError("Permission Denied");

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

    $iqReply = $IQ->Reply();
    $iqReply = $IQ->Reply("client");
    $iqReply = $IQ->Reply("transport");

Test functions

    $test = $IQ->DefinedTo();
    $test = $IQ->DefinedFrom();
    $test = $IQ->DefinedSTo();
    $test = $IQ->DefinedSFrom();
    $test = $IQ->DefinedEtherxTo();
    $test = $IQ->DefinedEtherxFrom();
    $test = $IQ->DefinedID();
    $test = $IQ->DefinedType();
    $test = $IQ->DefinedError();
    $test = $IQ->DefinedErrorCode();

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.

  GetSTo()      - returns either a string with the Jabber Identifier,
  GetSTo("jid")   or a Net::Jabber::JID object for the <host/> of the
                  conponent who is going to receive the <iq/>.  To 
                  get the JID object set the string to "jid", 
                  otherwise leave blank for the text string.

  GetSFrom()      -  returns either a string with the Jabber Identifier,
  GetSFrom("jid")    or a Net::Jabber::JID object for the <host/>
                     component who sent the <iq/>.  To get the JID 
                     object set the string to "jid", otherwise leave 
                     blank for the text string.

  GetEtherxTo(string) - returns the etherx:to attribute.  This is for
                        Transport writers who need to communicate with
                        Etherx.

  GetEtherxFrom(string) -  returns the etherx:from attribute.  This is for
                           Transport writers who need to communicate with
                           Etherx.

  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.

  GetErrorCode() - returns a string with the code 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
        sto=>string,         writing action.  If you set the "to"
        sfrom=>string,       attribute twice, the second setting is
        etherxto=>string,    what is used.  If you set the status, and
        etherxfrom=>string,  then set the priority then both will be in
        id=>string,          the <iq/> tag.  For valid settings read the
        type=>string,        specific Set functions below.
        errorcode=>string,
        error=>string)

  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...)

  SetSTo(string) - sets the sto attribute.  You can either pass a string
  SetSTo(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...)

  SetSFrom(string) - sets the sfrom attribute.  You can either pass a string
  SetSFrom(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...)

  SetEtherxTo(string) - sets the etherx:to attribute.  This is for
                        Transport writers who need to communicate with
                        Etherx.

  SetEtherxFrom(string) -  sets the etherx:from attribute.  This is for
                           Transport writers who need to communicate with
                           Etherx.

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

                    get     request information
                    set     set information

  SetErrorCode(string) - sets the error code 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.

  Reply(template=>string, - creates a new IQ object and populates
        type=>string)       the to/from and etherxto/etherxfrom fields
                            based the value of template.  The following
                            templates are available:

                            client: (default)
                                 just sets the to/from

                            transport:
                                 the transport will send the
                                 reply to the sender

                            The type will be set in the <iq/>.

Test functions

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

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

  DefinedSTo() - returns 1 if the sto attribute is defined in the <iq/>, 
                 0 otherwise.

  DefinedSFrom() - returns 1 if the sfrom attribute is defined in the <iq/>, 
                   0 otherwise.

  DefinedEtherxTo() - returns 1 if the etherx:to attribute is defined in 
                      the <iq/>, 0 otherwise.

  DefinedEtherxFrom() - returns 1 if the etherx:from attribute is defined 
                        in the <iq/>, 0 otherwise.

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

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

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

  DefinedErrorCode() - returns 1 if the code attribute is defined in
                       <error/>, 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.