1Net::XMPP::IQ(3)      User Contributed Perl Documentation     Net::XMPP::IQ(3)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

14         Net::XMPP::IQ differs from the other Net::XMPP::* modules in that
15         the XMLNS of the query is split out into a submodule under
16         IQ.  For specifics on each module please view the documentation
17         for the Net::XMPP::Namespaces module.
18
19         A Net::XMPP::IQ object is passed to the callback function for the
20         message.  Also, the first argument to the callback functions is the
21         session ID from XML::Stream.  There are some cases where you might
22         want this information, like if you created a Client that connects to
23         two servers at once, or for writing a mini server.
24
25           use Net::XMPP;
26
27           sub iq {
28             my ($sid,$IQ) = @_;
29             .
30             .
31             my $reply = $IQ->Reply();
32             my $replyQuery->GetQuery();
33             .
34           }
35
36         You now have access to all of the retrieval functions available.
37
38         To create a new iq to send to the server:
39
40           use Net::XMPP;
41
42           $IQ = Net::XMPP::IQ->new();
43           $IQType = $IQ->NewChild( type );
44           $IQType->SetXXXXX("yyyyy");
45
46         Now you can call the creation functions for the IQ, and for the
47         <query/> on the new query object itself.  See below for the <iq/>
48         functions, and in each query module for those functions.
49

METHODS

51   General functions
52         Reply(%args) - Creates a return <iq/> with the to and from
53                        filled in correctly, and a query object already
54                        added in.  The %args that you pass are passed
55                        to SetIQ() and will overwrite the IQ settings
56                        that Reply sets.
57
58   Retrieval functions
59         GetTo()      - returns either a string with the JID, or a
60         GetTo("jid")   Net::XMPP::JID object for the person who is
61                        going to receive the <iq/>.  To get the JID
62                        object set the string to "jid", otherwise leave
63                        blank for the text string.
64
65                        $to    = $IQ->GetTo();
66                        $toJID = $IQ->GetTo("jid");
67
68         GetFrom()      -  returns either a string with the JID, or a
69         GetFrom("jid")    Net::XMPP::JID object for the person who
70                           sent the <iq/>.  To get the JID object set
71                           the string to "jid", otherwise leave blank for the
72                           text string.
73
74                           $from    = $IQ->GetFrom();
75                           $fromJID = $IQ->GetFrom("jid");
76
77         GetType() - returns a string with the type <iq/> this is.
78
79                     $type = $IQ->GetType();
80
81         GetID() - returns an integer with the id of the <iq/>.
82
83                   $id = $IQ->GetID();
84
85         GetError() - returns a string with the text description of the error.
86
87                      $error = $IQ->GetError();
88
89         GetErrorCode() - returns a string with the code of error.
90
91                          $errorCode = $IQ->GetErrorCode();
92
93         GetQuery() - returns a Net::XMPP::Stanza object that contains the data
94                      in the query of the <iq/>.  Basically, it returns the
95                      first child in the <iq/>.
96
97                      $query = $IQ->GetQuery();
98
99         GetQueryXMLNS() - returns a string with the namespace of the query
100                           for this <iq/>, if one exists.
101
102                           $xmlns = $IQ->GetQueryXMLNS();
103
104   Creation functions
105         SetIQ(to=>string|JID,    - set multiple fields in the <iq/> at one
106               from=>string|JID,    time.  This is a cumulative and over
107               id=>string,          writing action.  If you set the "to"
108               type=>string,        attribute twice, the second setting is
109               errorcode=>string,   what is used.  If you set the status, and
110               error=>string)       then set the priority then both will be in
111                                    the <iq/> tag.  For valid settings read the
112                                    specific Set functions below.
113
114                                    $IQ->SetIQ(type=>"get",
115                                               to=>"bob\@jabber.org");
116
117                                    $IQ->SetIQ(to=>"bob\@jabber.org",
118                                               errorcode=>403,
119                                               error=>"Permission Denied");
120
121         SetTo(string) - sets the to attribute.  You can either pass a string
122         SetTo(JID)      or a JID object.  They must be a valid Jabber
123                         Identifiers or the server will return an error message.
124                         (ie.  bob@jabber.org, etc...)
125
126                         $IQ->SetTo("bob\@jabber.org");
127
128         SetFrom(string) - sets the from attribute.  You can either pass a
129         SetFrom(JID)      string or a JID object.  They must be a valid JIDs
130                           or the server will return an error message.
131                           (ie.  bob@jabber.org, etc...)
132
133                           $IQ->SetFrom("me\@jabber.org");
134
135         SetType(string) - sets the type attribute.  Valid settings are:
136
137                           get      request information
138                           set      set information
139                           result   results of a get
140                           error    there was an error
141
142                           $IQ->SetType("set");
143
144         SetErrorCode(string) - sets the error code of the <iq/>.
145
146                                $IQ->SetErrorCode(403);
147
148         SetError(string) - sets the error string of the <iq/>.
149
150                            $IQ->SetError("Permission Denied");
151
152         NewChild(string) - creates a new Net::XMPP::Stanza object with the
153                            namespace in the string.  In order for this
154                            function to work with a custom namespace, you
155                            must define and register that namespace with the
156                            IQ module.  For more information please read the
157                            documentation for Net::XMPP::Stanza.
158
159                            $queryObj = $IQ->NewChild("jabber:iq:auth");
160                            $queryObj = $IQ->NewChild("jabber:iq:roster");
161
162         Reply(hash) - creates a new IQ object and populates the to/from
163                       fields.  If you specify a hash the same as with SetIQ
164                       then those values will override the Reply values.
165
166                       $iqReply = $IQ->Reply();
167                       $iqReply = $IQ->Reply(type=>"result");
168
169   Removal functions
170         RemoveTo() - removes the to attribute from the <iq/>.
171
172                      $IQ->RemoveTo();
173
174         RemoveFrom() - removes the from attribute from the <iq/>.
175
176                        $IQ->RemoveFrom();
177
178         RemoveID() - removes the id attribute from the <iq/>.
179
180                      $IQ->RemoveID();
181
182         RemoveType() - removes the type attribute from the <iq/>.
183
184                        $IQ->RemoveType();
185
186         RemoveError() - removes the <error/> element from the <iq/>.
187
188                         $IQ->RemoveError();
189
190         RemoveErrorCode() - removes the code attribute from the <error/>
191                             element in the <iq/>.
192
193                             $IQ->RemoveErrorCode();
194
195   Test functions
196         DefinedTo() - returns 1 if the to attribute is defined in the <iq/>,
197                       0 otherwise.
198
199                       $test = $IQ->DefinedTo();
200
201         DefinedFrom() - returns 1 if the from attribute is defined in the
202                         <iq/>, 0 otherwise.
203
204                         $test = $IQ->DefinedFrom();
205
206         DefinedID() - returns 1 if the id attribute is defined in the <iq/>,
207                       0 otherwise.
208
209                       $test = $IQ->DefinedID();
210
211         DefinedType() - returns 1 if the type attribute is defined in the
212                         <iq/>, 0 otherwise.
213
214                         $test = $IQ->DefinedType();
215
216         DefinedError() - returns 1 if <error/> is defined in the <iq/>,
217                          0 otherwise.
218
219                          $test = $IQ->DefinedError();
220
221         DefinedErrorCode() - returns 1 if the code attribute is defined in
222                              <error/>, 0 otherwise.
223
224                              $test = $IQ->DefinedErrorCode();
225
226         DefinedQuery() - returns 1 if there is at least one namespaced
227                          child in the object.
228

AUTHOR

230       Originally authored by Ryan Eatmon.
231
232       Previously maintained by Eric Hacker.
233
234       Currently maintained by Darian Anthony Patrick.
235
237       This module is free software, you can redistribute it and/or modify it
238       under the LGPL 2.1.
239
240
241
242perl v5.34.0                      2022-01-21                  Net::XMPP::IQ(3)
Impressum