File Coverage

blib/lib/Net/XMPP/IQ.pm
Criterion Covered Total %
statement 42 43 97.6
branch 4 8 50.0
condition 1 3 33.3
subroutine 10 10 100.0
pod 0 3 0.0
total 57 67 85.0


line stmt bran cond sub pod time code
1             ##############################################################################
2             #
3             # This library is free software; you can redistribute it and/or
4             # modify it under the terms of the GNU Library General Public
5             # License as published by the Free Software Foundation; either
6             # version 2 of the License, or (at your option) any later version.
7             #
8             # This library is distributed in the hope that it will be useful,
9             # but WITHOUT ANY WARRANTY; without even the implied warranty of
10             # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11             # Library General Public License for more details.
12             #
13             # You should have received a copy of the GNU Library General Public
14             # License along with this library; if not, write to the
15             # Free Software Foundation, Inc., 59 Temple Place - Suite 330,
16             # Boston, MA 02111-1307, USA.
17             #
18             # Copyright (C) 1998-2004 Jabber Software Foundation http://jabber.org/
19             #
20             ##############################################################################
21              
22             package Net::XMPP::IQ;
23              
24             =head1 NAME
25              
26             Net::XMPP::IQ - XMPP Info/Query Module
27              
28             =head1 SYNOPSIS
29              
30             Net::XMPP::IQ is a companion to the Net::XMPP module. It
31             provides the user a simple interface to set and retrieve all
32             parts of an XMPP IQ.
33              
34             =head1 DESCRIPTION
35              
36             Net::XMPP::IQ differs from the other Net::XMPP::* modules in that
37             the XMLNS of the query is split out into a submodule under
38             IQ. For specifics on each module please view the documentation
39             for the Net::XMPP::Namespaces module.
40              
41             A Net::XMPP::IQ object is passed to the callback function for the
42             message. Also, the first argument to the callback functions is the
43             session ID from XML::Stream. There are some cases where you might
44             want this information, like if you created a Client that connects to
45             two servers at once, or for writing a mini server.
46              
47             use Net::XMPP;
48              
49             sub iq {
50             my ($sid,$IQ) = @_;
51             .
52             .
53             my $reply = $IQ->Reply();
54             my $replyQuery->GetQuery();
55             .
56             }
57              
58             You now have access to all of the retrieval functions available.
59              
60             To create a new iq to send to the server:
61              
62             use Net::XMPP;
63              
64             $IQ = Net::XMPP::IQ->new();
65             $IQType = $IQ->NewChild( type );
66             $IQType->SetXXXXX("yyyyy");
67              
68             Now you can call the creation functions for the IQ, and for the
69             on the new query object itself. See below for the
70             functions, and in each query module for those functions.
71              
72             =head1 METHODS
73              
74             =head2 General functions
75              
76             Reply(%args) - Creates a return with the to and from
77             filled in correctly, and a query object already
78             added in. The %args that you pass are passed
79             to SetIQ() and will overwrite the IQ settings
80             that Reply sets.
81              
82             =head2 Retrieval functions
83              
84             GetTo() - returns either a string with the JID, or a
85             GetTo("jid") Net::XMPP::JID object for the person who is
86             going to receive the . To get the JID
87             object set the string to "jid", otherwise leave
88             blank for the text string.
89              
90             $to = $IQ->GetTo();
91             $toJID = $IQ->GetTo("jid");
92              
93             GetFrom() - returns either a string with the JID, or a
94             GetFrom("jid") Net::XMPP::JID object for the person who
95             sent the . To get the JID object set
96             the string to "jid", otherwise leave blank for the
97             text string.
98              
99             $from = $IQ->GetFrom();
100             $fromJID = $IQ->GetFrom("jid");
101              
102             GetType() - returns a string with the type this is.
103              
104             $type = $IQ->GetType();
105              
106             GetID() - returns an integer with the id of the .
107              
108             $id = $IQ->GetID();
109              
110             GetError() - returns a string with the text description of the error.
111              
112             $error = $IQ->GetError();
113              
114             GetErrorCode() - returns a string with the code of error.
115              
116             $errorCode = $IQ->GetErrorCode();
117              
118             GetQuery() - returns a Net::XMPP::Stanza object that contains the data
119             in the query of the . Basically, it returns the
120             first child in the .
121              
122             $query = $IQ->GetQuery();
123              
124             GetQueryXMLNS() - returns a string with the namespace of the query
125             for this , if one exists.
126              
127             $xmlns = $IQ->GetQueryXMLNS();
128              
129             =head2 Creation functions
130              
131             SetIQ(to=>string|JID, - set multiple fields in the at one
132             from=>string|JID, time. This is a cumulative and over
133             id=>string, writing action. If you set the "to"
134             type=>string, attribute twice, the second setting is
135             errorcode=>string, what is used. If you set the status, and
136             error=>string) then set the priority then both will be in
137             the tag. For valid settings read the
138             specific Set functions below.
139              
140             $IQ->SetIQ(type=>"get",
141             to=>"bob\@jabber.org");
142              
143             $IQ->SetIQ(to=>"bob\@jabber.org",
144             errorcode=>403,
145             error=>"Permission Denied");
146              
147             SetTo(string) - sets the to attribute. You can either pass a string
148             SetTo(JID) or a JID object. They must be a valid Jabber
149             Identifiers or the server will return an error message.
150             (ie. bob@jabber.org, etc...)
151              
152             $IQ->SetTo("bob\@jabber.org");
153              
154             SetFrom(string) - sets the from attribute. You can either pass a
155             SetFrom(JID) string or a JID object. They must be a valid JIDs
156             or the server will return an error message.
157             (ie. bob@jabber.org, etc...)
158              
159             $IQ->SetFrom("me\@jabber.org");
160              
161             SetType(string) - sets the type attribute. Valid settings are:
162              
163             get request information
164             set set information
165             result results of a get
166             error there was an error
167              
168             $IQ->SetType("set");
169              
170             SetErrorCode(string) - sets the error code of the .
171              
172             $IQ->SetErrorCode(403);
173              
174             SetError(string) - sets the error string of the .
175              
176             $IQ->SetError("Permission Denied");
177              
178             NewChild(string) - creates a new Net::XMPP::Stanza object with the
179             namespace in the string. In order for this
180             function to work with a custom namespace, you
181             must define and register that namespace with the
182             IQ module. For more information please read the
183             documentation for Net::XMPP::Stanza.
184              
185             $queryObj = $IQ->NewChild("jabber:iq:auth");
186             $queryObj = $IQ->NewChild("jabber:iq:roster");
187              
188             Reply(hash) - creates a new IQ object and populates the to/from
189             fields. If you specify a hash the same as with SetIQ
190             then those values will override the Reply values.
191              
192             $iqReply = $IQ->Reply();
193             $iqReply = $IQ->Reply(type=>"result");
194              
195             =head2 Removal functions
196              
197             RemoveTo() - removes the to attribute from the .
198              
199             $IQ->RemoveTo();
200              
201             RemoveFrom() - removes the from attribute from the .
202              
203             $IQ->RemoveFrom();
204              
205             RemoveID() - removes the id attribute from the .
206              
207             $IQ->RemoveID();
208              
209             RemoveType() - removes the type attribute from the .
210              
211             $IQ->RemoveType();
212              
213             RemoveError() - removes the element from the .
214              
215             $IQ->RemoveError();
216              
217             RemoveErrorCode() - removes the code attribute from the
218             element in the .
219              
220             $IQ->RemoveErrorCode();
221              
222             =head2 Test functions
223              
224             DefinedTo() - returns 1 if the to attribute is defined in the ,
225             0 otherwise.
226              
227             $test = $IQ->DefinedTo();
228              
229             DefinedFrom() - returns 1 if the from attribute is defined in the
230             , 0 otherwise.
231              
232             $test = $IQ->DefinedFrom();
233              
234             DefinedID() - returns 1 if the id attribute is defined in the ,
235             0 otherwise.
236              
237             $test = $IQ->DefinedID();
238              
239             DefinedType() - returns 1 if the type attribute is defined in the
240             , 0 otherwise.
241              
242             $test = $IQ->DefinedType();
243              
244             DefinedError() - returns 1 if is defined in the ,
245             0 otherwise.
246              
247             $test = $IQ->DefinedError();
248              
249             DefinedErrorCode() - returns 1 if the code attribute is defined in
250             , 0 otherwise.
251              
252             $test = $IQ->DefinedErrorCode();
253              
254             DefinedQuery() - returns 1 if there is at least one namespaced
255             child in the object.
256              
257             =head1 AUTHOR
258              
259             Originally authored by Ryan Eatmon.
260              
261             Previously maintained by Eric Hacker.
262              
263             Currently maintained by Darian Anthony Patrick.
264              
265             =head1 COPYRIGHT
266              
267             This module is free software, you can redistribute it and/or modify it
268             under the LGPL 2.1.
269              
270             =cut
271              
272             require 5.008;
273 15     15   58 use strict;
  15         20  
  15         436  
274 15     15   52 use warnings;
  15         16  
  15         313  
275 15     15   105 use Carp;
  15         19  
  15         982  
276 15     15   71 use vars qw( %FUNCTIONS );
  15         26  
  15         562  
277 15     15   60 use Net::XMPP::Stanza;
  15         18  
  15         303  
278 15     15   53 use base qw( Net::XMPP::Stanza );
  15         23  
  15         5919  
279              
280             sub new
281             {
282 4     4 0 794 my $proto = shift;
283 4   33     20 my $class = ref($proto) || $proto;
284 4         10 my $self = { };
285              
286 4         10 bless($self, $proto);
287              
288 4         21 $self->{DEBUGHEADER} = "IQ";
289 4         9 $self->{TAG} = "iq";
290              
291 4         10 $self->{FUNCS} = \%FUNCTIONS;
292              
293 4         23 $self->_init(@_);
294              
295 4         7 return $self;
296             }
297              
298 1     1   3 sub _iq { my $self = shift; return Net::XMPP::IQ->new(); }
  1         6  
299              
300             $FUNCTIONS{Error}->{path} = 'error/text()';
301              
302             $FUNCTIONS{ErrorCode}->{path} = 'error/@code';
303              
304             $FUNCTIONS{From}->{type} = 'jid';
305             $FUNCTIONS{From}->{path} = '@from';
306              
307             $FUNCTIONS{ID}->{path} = '@id';
308              
309             $FUNCTIONS{To}->{type} = 'jid';
310             $FUNCTIONS{To}->{path} = '@to';
311              
312             $FUNCTIONS{Type}->{path} = '@type';
313              
314             $FUNCTIONS{XMLNS}->{path} = '@xmlns';
315              
316             $FUNCTIONS{IQ}->{type} = 'master';
317              
318             $FUNCTIONS{Child}->{type} = 'child';
319             $FUNCTIONS{Child}->{path} = '*[@xmlns]';
320             $FUNCTIONS{Child}->{child} = { };
321              
322             $FUNCTIONS{Query}->{type} = 'child';
323             $FUNCTIONS{Query}->{path} = '*[@xmlns][0]';
324             $FUNCTIONS{Query}->{child} = { child_index=>0 };
325              
326             ##############################################################################
327             #
328             # GetQueryXMLNS - returns the xmlns of the first child
329             #
330             ##############################################################################
331             sub GetQueryXMLNS
332             {
333 1     1 0 3 my $self = shift;
334 1 50       2 return $self->{CHILDREN}->[0]->GetXMLNS() if ($#{$self->{CHILDREN}} > -1);
  1         14  
335             }
336              
337              
338             ##############################################################################
339             #
340             # Reply - returns a Net::XMPP::IQ object with the proper fields
341             # already populated for you.
342             #
343             ##############################################################################
344             sub Reply
345             {
346 1     1 0 7 my $self = shift;
347 1         3 my %args;
348 1         18 while($#_ >= 0) { $args{ lc pop(@_) } = pop(@_); }
  0         0  
349              
350 1         6 my $reply = $self->_iq();
351              
352 1 50       7 $reply->SetID($self->GetID()) if ($self->GetID() ne "");
353 1         17 $reply->SetType("result");
354              
355 1         27 $reply->NewChild($self->GetQueryXMLNS());
356              
357 1 50       6 $reply->SetIQ((($self->GetFrom() ne "") ?
    50          
358             (to=>$self->GetFrom()) :
359             ()
360             ),
361             (($self->GetTo() ne "") ?
362             (from=>$self->GetTo()) :
363             ()
364             ),
365             );
366 1         7 $reply->SetIQ(%args);
367              
368 1         4 return $reply;
369             }
370              
371              
372             1;