source: perl/modules/Jabber/lib/Net/XMPP/IQ.pm

barnowl_perlaimdebianrelease-1.4release-1.5release-1.6release-1.7release-1.8release-1.9
Last change on this file was c2bed55, checked in by Nelson Elhage <nelhage@mit.edu>, 14 years ago
Moving Net::Jabber into Jabber.par
  • Property mode set to 100644
File size: 11.1 KB
Line 
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
22package Net::XMPP::IQ;
23
24=head1 NAME
25
26Net::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  <query/> on the new query object itself.  See below for the <iq/>
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 <iq/> 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 <iq/>.  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 <iq/>.  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 <iq/> this is.
103
104              $type = $IQ->GetType();
105
106  GetID() - returns an integer with the id of the <iq/>.
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 <iq/>.  Basically, it returns the
120               first child in the <iq/>.
121
122               $query = $IQ->GetQuery();
123
124  GetQueryXMLNS() - returns a string with the namespace of the query
125                    for this <iq/>, if one exists.
126
127                    $xmlns = $IQ->GetQueryXMLNS();
128
129=head2 Creation functions
130
131  SetIQ(to=>string|JID,    - set multiple fields in the <iq/> 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 <iq/> 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 <iq/>.
171
172                         $IQ->SetErrorCode(403);
173
174  SetError(string) - sets the error string of the <iq/>.
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 <iq/>.
198
199               $IQ->RemoveTo();
200 
201  RemoveFrom() - removes the from attribute from the <iq/>.
202
203                 $IQ->RemoveFrom();
204 
205  RemoveID() - removes the id attribute from the <iq/>.
206
207               $IQ->RemoveID();
208 
209  RemoveType() - removes the type attribute from the <iq/>.
210
211                 $IQ->RemoveType();
212 
213  RemoveError() - removes the <error/> element from the <iq/>.
214
215                  $IQ->RemoveError();
216 
217  RemoveErrorCode() - removes the code attribute from the <error/>
218                      element in the <iq/>.
219
220                      $IQ->RemoveErrorCode();
221
222=head2 Test functions
223
224  DefinedTo() - returns 1 if the to attribute is defined in the <iq/>,
225                0 otherwise.
226
227                $test = $IQ->DefinedTo();
228
229  DefinedFrom() - returns 1 if the from attribute is defined in the
230                  <iq/>, 0 otherwise.
231
232                  $test = $IQ->DefinedFrom();
233
234  DefinedID() - returns 1 if the id attribute is defined in the <iq/>,
235                0 otherwise.
236
237                $test = $IQ->DefinedID();
238
239  DefinedType() - returns 1 if the type attribute is defined in the
240                  <iq/>, 0 otherwise.
241
242                  $test = $IQ->DefinedType();
243
244  DefinedError() - returns 1 if <error/> is defined in the <iq/>,
245                   0 otherwise.
246
247                   $test = $IQ->DefinedError();
248
249  DefinedErrorCode() - returns 1 if the code attribute is defined in
250                       <error/>, 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
259Ryan Eatmon
260
261=head1 COPYRIGHT
262
263This module is free software; you can redistribute it and/or modify
264it under the same terms as Perl itself.
265
266=cut
267
268require 5.003;
269use strict;
270use Carp;
271use vars qw( %FUNCTIONS );
272use Net::XMPP::Stanza;
273use base qw( Net::XMPP::Stanza );
274
275sub new
276{
277    my $proto = shift;
278    my $class = ref($proto) || $proto;
279    my $self = { };
280
281    bless($self, $proto);
282
283    $self->{DEBUGHEADER} = "IQ";
284    $self->{TAG} = "iq";
285
286    $self->{FUNCS} = \%FUNCTIONS;
287   
288    $self->_init(@_);
289
290    return $self;
291}
292
293sub _iq { my $self = shift; return Net::XMPP::IQ->new(); }
294
295$FUNCTIONS{Error}->{path} = 'error/text()';
296
297$FUNCTIONS{ErrorCode}->{path} = 'error/@code';
298
299$FUNCTIONS{From}->{type} = 'jid';
300$FUNCTIONS{From}->{path} = '@from';
301
302$FUNCTIONS{ID}->{path} = '@id';
303
304$FUNCTIONS{To}->{type} = 'jid';
305$FUNCTIONS{To}->{path} = '@to';
306
307$FUNCTIONS{Type}->{path} = '@type';
308
309$FUNCTIONS{XMLNS}->{path} = '@xmlns';
310
311$FUNCTIONS{IQ}->{type}  = 'master';
312
313$FUNCTIONS{Child}->{type}  = 'child';
314$FUNCTIONS{Child}->{path}  = '*[@xmlns]';
315$FUNCTIONS{Child}->{child} = { };
316
317$FUNCTIONS{Query}->{type}  = 'child';
318$FUNCTIONS{Query}->{path}  = '*[@xmlns][0]';
319$FUNCTIONS{Query}->{child} = { child_index=>0 };
320
321##############################################################################
322#
323# GetQueryXMLNS - returns the xmlns of the first child
324#
325##############################################################################
326sub GetQueryXMLNS
327{
328    my $self = shift;
329    return $self->{CHILDREN}->[0]->GetXMLNS() if ($#{$self->{CHILDREN}} > -1);
330}
331
332
333##############################################################################
334#
335# Reply - returns a Net::XMPP::IQ object with the proper fields
336#         already populated for you.
337#
338##############################################################################
339sub Reply
340{
341    my $self = shift;
342    my %args;
343    while($#_ >= 0) { $args{ lc pop(@_) } = pop(@_); }
344
345    my $reply = $self->_iq();
346
347    $reply->SetID($self->GetID()) if ($self->GetID() ne "");
348    $reply->SetType("result");
349
350    $reply->NewChild($self->GetQueryXMLNS());
351
352    $reply->SetIQ((($self->GetFrom() ne "") ?
353                   (to=>$self->GetFrom()) :
354                   ()
355                  ),
356                  (($self->GetTo() ne "") ?
357                   (from=>$self->GetTo()) :
358                   ()
359                  ),
360                 );
361    $reply->SetIQ(%args);
362
363    return $reply;
364}
365
366
3671;
Note: See TracBrowser for help on using the repository browser.