source: perl/lib/Net/Jabber/Data.pm @ 72a53e9

barnowl_perlaimdebianrelease-1.10release-1.4release-1.5release-1.6release-1.7release-1.8release-1.9
Last change on this file since 72a53e9 was 0ff8d110, checked in by Alejandro R. Sedeño <asedeno@mit.edu>, 18 years ago
Adding XML::Stream, Net::XMPP, and Net::Jabber to perl/lib/
  • Property mode set to 100644
File size: 13.6 KB
RevLine 
[0ff8d110]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#  Jabber
19#  Copyright (C) 1998-1999 The Jabber Team http://jabber.org/
20#
21##############################################################################
22
23package Net::Jabber::Data;
24
25=head1 NAME
26
27Net::Jabber::Data - Jabber Data Library
28
29=head1 SYNOPSIS
30
31  Net::Jabber::Data is a companion to the Net::Jabber::XDB module. It
32  provides the user a simple interface to set and retrieve all
33  parts of a Jabber XDB Data.
34
35=head1 DESCRIPTION
36
37  Net::Jabber::Data differs from the other modules in that its behavior
38  and available functions are based off of the XML namespace that is
39  set in it.  The current list of supported namespaces is:
40
41    jabber:iq:auth
42    jabber:iq:auth:0k
43    jabber:iq:register
44    jabber:iq:roster
45
46  For more information on what these namespaces are for, visit
47  http://www.jabber.org and browse the Jabber Programmers Guide.
48
49  Each of these namespaces provide Net::Jabber::Data with the functions
50  to access the data.  By using the AUTOLOAD function the functions for
51  each namespace is used when that namespace is active.
52
53  To access a Data object you must create an XDB object and use the
54  access functions there to get to the Data.  To initialize the XDB with
55  a Jabber <xdb/> you must pass it the XML::Stream hash from the
56  Net::Jabber::Client module.
57
58    my $xdb = new Net::Jabber::XDB(%hash);
59
60  There has been a change from the old way of handling the callbacks.
61  You no longer have to do the above yourself, a Net::Jabber::XDB
62  object is passed to the callback function for the message.  Also,
63  the first argument to the callback functions is the session ID from
64  XML::Streams.  There are some cases where you might want this
65  information, like if you created a Client that connects to two servers
66  at once, or for writing a mini server.
67
68    use Net::Jabber qw(Client);
69
70    sub xdbCB {
71      my ($sid,$XDB) = @_;
72      my $data = $XDB->GetData();
73      .
74      .
75      .
76    }
77
78  You now have access to all of the retrieval functions available for
79  that namespace.
80
81  To create a new xdb to send to the server:
82
83    use Net::Jabber;
84
85    my $xdb = new Net::Jabber::XDB();
86    $data = $xdb->NewData("jabber:iq:auth");
87
88  Now you can call the creation functions for the Data as defined in the
89  proper namespaces.  See below for the general <data/> functions, and
90  in each data module for those functions.
91
92  For more information about the array format being passed to the
93  CallBack please read the Net::Jabber::Client documentation.
94
95=head1 METHODS
96
97=head2 Retrieval functions
98
99  GetXMLNS() - returns a string with the namespace of the data that
100               the <xdb/> contains.
101
102               $xmlns  = $XDB->GetXMLNS();
103
104  GetData() - since the behavior of this module depends on the
105               namespace, a Data object may contain Data objects.
106               This helps to leverage code reuse by making children
107               behave in the same manner.  More than likely this
108               function will never be called.
109
110               @data = GetData()
111
112=head2 Creation functions
113
114  SetXMLNS(string) - sets the xmlns of the <data/> to the string.
115
116                     $data->SetXMLNS("jabber:xdb:roster");
117
118
119In an effort to make maintaining this document easier, I am not going
120to go into full detail on each of these functions.  Rather I will
121present the functions in a list with a type in the first column to
122show what they return, or take as arugments.  Here is the list of
123types I will use:
124
125  string  - just a string
126  array   - array of strings
127  flag    - this means that the specified child exists in the
128            XML <child/> and acts like a flag.  get will return
129            0 or 1.
130  JID     - either a string or Net::Jabber::JID object.
131  objects - creates new objects, or returns an array of
132            objects.
133  special - this is a special case kind of function.  Usually
134            just by calling Set() with no arguments it will
135            default the value to a special value, like OS or time.
136            Sometimes it will modify the value you set, like
137            in jabber:xdb:version SetVersion() the function
138            adds on the Net::Jabber version to the string
139            just for advertisement purposes. =)
140  master  - this desribes a function that behaves like the
141            SetMessage() function in Net::Jabber::Message.
142            It takes a hash and sets all of the values defined,
143            and the Set returns a hash with the values that
144            are defined in the object.
145
146=head1 jabber:iq:
147
148  Type     Get               Set               Defined
149  =======  ================  ================  ==================
150
151
152=head1 jabber:iq:
153
154  Type     Get               Set               Defined
155  =======  ================  ================  ==================
156
157
158=head1 jabber:iq:
159
160  Type     Get               Set               Defined
161  =======  ================  ================  ==================
162
163
164=head1 jabber:iq:
165
166  Type     Get               Set               Defined
167  =======  ================  ================  ==================
168
169
170=head1 jabber:iq:
171
172  Type     Get               Set               Defined
173  =======  ================  ================  ==================
174
175
176=head1 CUSTOM NAMESPACES
177
178  Part of the flexability of this module is that you can define your own
179  namespace.  For more information on this topic, please read the
180  Net::Jabber::Namespaces man page.
181
182=head1 AUTHOR
183
184By Ryan Eatmon in May of 2001 for http://jabber.org..
185
186=head1 COPYRIGHT
187
188This module is free software; you can redistribute it and/or modify
189it under the same terms as Perl itself.
190
191=cut
192
193require 5.003;
194use strict;
195use Carp;
196use vars qw($VERSION $AUTOLOAD %FUNCTIONS %NAMESPACES);
197
198$VERSION = "2.0";
199
200sub new
201{
202    my $proto = shift;
203    my $class = ref($proto) || $proto;
204    my $self = { };
205
206    $self->{VERSION} = $VERSION;
207
208    bless($self, $proto);
209
210    $self->{DEBUGHEADER} = "Data";
211
212    $self->{DATA} = {};
213    $self->{CHILDREN} = {};
214
215    $self->{TAG} = "data";
216
217    if ("@_" ne (""))
218    {
219        if (ref($_[0]) eq "Net::Jabber::Data")
220        {
221            return $_[0];
222        }
223        else
224        {
225            $self->{TREE} = shift;
226            $self->{TAG} = $self->{TREE}->get_tag();
227            $self->ParseXMLNS();
228            $self->ParseTree();
229        }
230    }
231
232    return $self;
233}
234
235
236##############################################################################
237#
238# AUTOLOAD - This function calls the main AutoLoad function in Jabber.pm
239#
240##############################################################################
241sub AUTOLOAD
242{
243    my $self = shift;
244    &Net::Jabber::AutoLoad($self,$AUTOLOAD,@_);
245}
246
247$FUNCTIONS{XMLNS}->{Get}     = "xmlns";
248$FUNCTIONS{XMLNS}->{Set}     = ["scalar","xmlns"];
249$FUNCTIONS{XMLNS}->{Defined} = "xmlns";
250$FUNCTIONS{XMLNS}->{Hash}    = "att";
251
252$FUNCTIONS{Data}->{Get}     = "__netjabber__:children:data";
253$FUNCTIONS{Data}->{Defined} = "__netjabber__:children:data";
254
255#-----------------------------------------------------------------------------
256# jabber:iq:auth
257#-----------------------------------------------------------------------------
258$NAMESPACES{"jabber:iq:auth"}->{Password}->{Get}     = "password";
259$NAMESPACES{"jabber:iq:auth"}->{Password}->{Set}     = ["scalar","password"];
260$NAMESPACES{"jabber:iq:auth"}->{Password}->{Defined} = "password";
261$NAMESPACES{"jabber:iq:auth"}->{Password}->{Hash}    = "data";
262
263$NAMESPACES{"jabber:iq:auth"}->{Auth}->{Get} = "__netjabber__:master";
264$NAMESPACES{"jabber:iq:auth"}->{Auth}->{Set} = ["master"];
265
266$NAMESPACES{"jabber:iq:auth"}->{"__netjabber__"}->{Tag} = "password";
267
268#-----------------------------------------------------------------------------
269# jabber:iq:auth:0k
270#-----------------------------------------------------------------------------
271$NAMESPACES{"jabber:iq:auth:0k"}->{Hash}->{Get}     = "hash";
272$NAMESPACES{"jabber:iq:auth:0k"}->{Hash}->{Set}     = ["scalar","hash"];
273$NAMESPACES{"jabber:iq:auth:0k"}->{Hash}->{Defined} = "hash";
274$NAMESPACES{"jabber:iq:auth:0k"}->{Hash}->{Hash}    = "child-data";
275
276$NAMESPACES{"jabber:iq:auth:0k"}->{Sequence}->{Get}     = "sequence";
277$NAMESPACES{"jabber:iq:auth:0k"}->{Sequence}->{Set}     = ["scalar","sequence"];
278$NAMESPACES{"jabber:iq:auth:0k"}->{Sequence}->{Defined} = "sequence";
279$NAMESPACES{"jabber:iq:auth:0k"}->{Sequence}->{Hash}    = "child-data";
280
281$NAMESPACES{"jabber:iq:auth:0k"}->{Token}->{Get}     = "token";
282$NAMESPACES{"jabber:iq:auth:0k"}->{Token}->{Set}     = ["scalar","token"];
283$NAMESPACES{"jabber:iq:auth:0k"}->{Token}->{Defined} = "token";
284$NAMESPACES{"jabber:iq:auth:0k"}->{Token}->{Hash}    = "child-data";
285
286$NAMESPACES{"jabber:iq:auth:0k"}->{ZeroK}->{Get} = "__netjabber__:master";
287$NAMESPACES{"jabber:iq:auth:0k"}->{ZeroK}->{Set} = ["master"];
288
289$NAMESPACES{"jabber:iq:auth:0k"}->{"__netjabber__"}->{Tag} = "zerok";
290
291#-----------------------------------------------------------------------------
292# jabber:iq:last
293#-----------------------------------------------------------------------------
294$NAMESPACES{"jabber:iq:last"}->{Message}->{Get}     = "message";
295$NAMESPACES{"jabber:iq:last"}->{Message}->{Set}     = ["scalar","message"];
296$NAMESPACES{"jabber:iq:last"}->{Message}->{Defined} = "message";
297$NAMESPACES{"jabber:iq:last"}->{Message}->{Hash}    = "data";
298
299$NAMESPACES{"jabber:iq:last"}->{Seconds}->{Get}     = "last";
300$NAMESPACES{"jabber:iq:last"}->{Seconds}->{Set}     = ["scalar","last"];
301$NAMESPACES{"jabber:iq:last"}->{Seconds}->{Defined} = "last";
302$NAMESPACES{"jabber:iq:last"}->{Seconds}->{Hash}    = "att";
303
304$NAMESPACES{"jabber:iq:last"}->{Last}->{Get} = "__netjabber__:master";
305$NAMESPACES{"jabber:iq:last"}->{Last}->{Set} = ["master"];
306
307$NAMESPACES{"jabber:iq:last"}->{"__netjabber__"}->{Tag} = "query";
308
309#-----------------------------------------------------------------------------
310# jabber:iq:roster
311#-----------------------------------------------------------------------------
312$NAMESPACES{"jabber:iq:roster"}->{Item}->{Get}     = "";
313$NAMESPACES{"jabber:iq:roster"}->{Item}->{Set}     = ["add","Data","__netjabber__:iq:roster:item"];
314$NAMESPACES{"jabber:iq:roster"}->{Item}->{Defined} = "__netjabber__:children:data";
315$NAMESPACES{"jabber:iq:roster"}->{Item}->{Hash}    = "child-add";
316
317$NAMESPACES{"jabber:iq:roster"}->{Item}->{Add} = ["Data","__netjabber__:iq:roster:item","Item","item"];
318
319$NAMESPACES{"jabber:iq:roster"}->{Items}->{Get} = ["__netjabber__:children:data","__netjabber__:iq:roster:item"];
320
321$NAMESPACES{"jabber:iq:roster"}->{"__netjabber__"}->{Tag} = "query";
322
323#-----------------------------------------------------------------------------
324# __netjabber__:iq:roster:item
325#-----------------------------------------------------------------------------
326$NAMESPACES{"__netjabber__:iq:roster:item"}->{Ask}->{Get}     = "ask";
327$NAMESPACES{"__netjabber__:iq:roster:item"}->{Ask}->{Set}     = ["scalar","ask"];
328$NAMESPACES{"__netjabber__:iq:roster:item"}->{Ask}->{Defined} = "ask";
329$NAMESPACES{"__netjabber__:iq:roster:item"}->{Ask}->{Hash}    = "att";
330
331$NAMESPACES{"__netjabber__:iq:roster:item"}->{Group}->{Get}     = "group";
332$NAMESPACES{"__netjabber__:iq:roster:item"}->{Group}->{Set}     = ["array","group"];
333$NAMESPACES{"__netjabber__:iq:roster:item"}->{Group}->{Defined} = "group";
334$NAMESPACES{"__netjabber__:iq:roster:item"}->{Group}->{Hash}    = "child-data";
335
336$NAMESPACES{"__netjabber__:iq:roster:item"}->{JID}->{Get}     = "jid";
337$NAMESPACES{"__netjabber__:iq:roster:item"}->{JID}->{Set}     = ["jid","jid"];
338$NAMESPACES{"__netjabber__:iq:roster:item"}->{JID}->{Defined} = "jid";
339$NAMESPACES{"__netjabber__:iq:roster:item"}->{JID}->{Hash}    = "att";
340
341$NAMESPACES{"__netjabber__:iq:roster:item"}->{Name}->{Get}     = "name";
342$NAMESPACES{"__netjabber__:iq:roster:item"}->{Name}->{Set}     = ["scalar","name"];
343$NAMESPACES{"__netjabber__:iq:roster:item"}->{Name}->{Defined} = "name";
344$NAMESPACES{"__netjabber__:iq:roster:item"}->{Name}->{Hash}    = "att";
345
346$NAMESPACES{"__netjabber__:iq:roster:item"}->{Subscription}->{Get}     = "subscription";
347$NAMESPACES{"__netjabber__:iq:roster:item"}->{Subscription}->{Set}     = ["scalar","subscription"];
348$NAMESPACES{"__netjabber__:iq:roster:item"}->{Subscription}->{Defined} = "subscription";
349$NAMESPACES{"__netjabber__:iq:roster:item"}->{Subscription}->{Hash}    = "att";
350
351$NAMESPACES{"__netjabber__:iq:roster:item"}->{Item}->{Get} = "__netjabber__:master";
352$NAMESPACES{"__netjabber__:iq:roster:item"}->{Item}->{Set} = ["master"];
353
354#-----------------------------------------------------------------------------
355# jabber:x:offline
356#-----------------------------------------------------------------------------
357$NAMESPACES{"jabber:x:offline"}->{Data}->{Get}     = "data";
358$NAMESPACES{"jabber:x:offline"}->{Data}->{Set}     = ["scalar","data"];
359$NAMESPACES{"jabber:x:offline"}->{Data}->{Defined} = "data";
360$NAMESPACES{"jabber:x:offline"}->{Data}->{Hash}    = "data";
361
362$NAMESPACES{"jabber:x:offline"}->{Offline}->{Get} = "__netjabber__:master";
363$NAMESPACES{"jabber:x:offline"}->{Offline}->{Set} = ["master"];
364
365$NAMESPACES{"jabber:x:offline"}->{"__netjabber__"}->{Tag} = "foo";
366
3671;
Note: See TracBrowser for help on using the repository browser.