net::xmpp::iq(3pm)

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

Ryan Eatmon

COPYRIGHT

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

perl v5.10.0 2008-07-09 Net::XMPP::IQ(3pm)