Net::XMPP::IQ - XMPP Info/Query Module

- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS
  - General functions
  - Retrieval functions
  - Creation functions
  - Removal functions
  - Test functions
- AUTHOR
- COPYRIGHT

# NAME

Net::XMPP::IQ - XMPP Info/Query Module

# SYNOPSIS

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

# DESCRIPTION

      Net::XMPP::IQ differs from the other Net::XMPP::* modules in that
      the XMLNS of the query is split out into a submodule under
      IQ.  For specifics on each module please view the documentation
      for the Net::XMPP::Namespaces module.

      A Net::XMPP::IQ object is passed to the callback function for the
      message.  Also, the first argument to the callback functions is the
      session ID from XML::Stream.  There are some cases where you might
      want this information, like if you created a Client that connects to
      two servers at once, or for writing a mini server.

        use Net::XMPP;

        sub iq {
          my ($sid,$IQ) = @_;
          .
          .
          my $reply = $IQ->Reply();
          my $replyQuery->GetQuery();
          .
        }

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

      To create a new iq to send to the server:

        use Net::XMPP;

        $IQ = Net::XMPP::IQ->new();
        $IQType = $IQ->NewChild( 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.

# METHODS

## General functions

      Reply(%args) - Creates a return <iq/> with the to and from
                     filled in correctly, and a query object already
                     added in.  The %args that you pass are passed
                     to SetIQ() and will overwrite the IQ settings
                     that Reply sets.

## Retrieval functions

      GetTo()      - returns either a string with the JID, or a
      GetTo("jid")   Net::XMPP::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.

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

      GetFrom()      -  returns either a string with the JID, or a
      GetFrom("jid")    Net::XMPP::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.

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

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

                  $type = $IQ->GetType();

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

                $id = $IQ->GetID();

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

                   $error = $IQ->GetError();

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

                       $errorCode = $IQ->GetErrorCode();

      GetQuery() - returns a Net::XMPP::Stanza object that contains the data
                   in the query of the <iq/>.  Basically, it returns the
                   first child in the <iq/>.

                   $query = $IQ->GetQuery();

      GetQueryXMLNS() - returns a string with the namespace of the query
                        for this <iq/>, if one exists.

                        $xmlns = $IQ->GetQueryXMLNS();

## Creation functions

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

                                 $IQ->SetIQ(type=>"get",
                                            to=>"bob\@jabber.org");

                                 $IQ->SetIQ(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.  bob@jabber.org, etc...)

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

      SetFrom(string) - sets the from attribute.  You can either pass a
      SetFrom(JID)      string or a JID object.  They must be a valid JIDs
                        or the server will return an error message.
                        (ie.  bob@jabber.org, etc...)

                        $IQ->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

                        $IQ->SetType("set");

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

                             $IQ->SetErrorCode(403);

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

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

      NewChild(string) - creates a new Net::XMPP::Stanza 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::XMPP::Stanza.

                         $queryObj = $IQ->NewChild("jabber:iq:auth");
                         $queryObj = $IQ->NewChild("jabber:iq:roster");

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

                    $iqReply = $IQ->Reply();
                    $iqReply = $IQ->Reply(type=>"result");

## Removal functions

      RemoveTo() - removes the to attribute from the <iq/>.

                   $IQ->RemoveTo();

      RemoveFrom() - removes the from attribute from the <iq/>.

                     $IQ->RemoveFrom();

      RemoveID() - removes the id attribute from the <iq/>.

                   $IQ->RemoveID();

      RemoveType() - removes the type attribute from the <iq/>.

                     $IQ->RemoveType();

      RemoveError() - removes the <error/> element from the <iq/>.

                      $IQ->RemoveError();

      RemoveErrorCode() - removes the code attribute from the <error/>
                          element in the <iq/>.

                          $IQ->RemoveErrorCode();

## Test functions

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

                    $test = $IQ->DefinedTo();

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

                      $test = $IQ->DefinedFrom();

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

                    $test = $IQ->DefinedID();

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

                      $test = $IQ->DefinedType();

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

                       $test = $IQ->DefinedError();

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

                           $test = $IQ->DefinedErrorCode();

      DefinedQuery() - returns 1 if there is at least one namespaced
                       child in the object.

# AUTHOR

Originally authored by Ryan Eatmon.

Previously maintained by Eric Hacker.

Currently maintained by Darian Anthony Patrick.

# COPYRIGHT

This module is free software, you can redistribute it and/or modify it under the LGPL 2.1.

Net::XMPP::IQ - XMPP Info/Query Module