1XML::Stream(3)        User Contributed Perl Documentation       XML::Stream(3)
2
3
4

NAME

6       XML::Stream - Creates an XML Stream connection and parses return data
7

SYNOPSIS

9       XML::Stream is an attempt at solidifying the use of XML via streaming.
10

DESCRIPTION

12       This module provides the user with methods to connect to a remote
13       server, send a stream of XML to the server, and receive/parse an XML
14       stream from the server.  It is primarily based work for the Etherx XML
15       router developed by the Jabber Development Team.  For more information
16       about this project visit http://xmpp.org/protocols/streams/.
17
18       XML::Stream gives the user the ability to define a central callback
19       that will be used to handle the tags received from the server.  These
20       tags are passed in the format defined at instantiation time.  the
21       closing tag of an object is seen, the tree is finished and passed to
22       the call back function.  What the user does with it from there is up to
23       them.
24
25       For a detailed description of how this module works, and about the data
26       structure that it returns, please view the source of Stream.pm and look
27       at the detailed description at the end of the file.
28
29       NOTE: The parser that XML::Stream::Parser provides, as are most Perl
30       parsers, is synchronous.  If you are in the middle of parsing a packet
31       and call a user defined callback, the Parser is blocked until your
32       callback finishes.  This means you cannot be operating on a packet,
33       send out another packet and wait for a response to that packet.  It
34       will never get to you.  Threading might solve this, but as we all know
35       threading in Perl is not quite up to par yet.  This issue will be
36       revisted in the future.
37

METHODS

39   new
40         new(
41             debug      => string,
42             debugfh    => FileHandle,
43             debuglevel => 0|1|N,
44             debugtime  => 0|1,
45             style      => string)
46
47       Creates the XML::Stream object.  debug should be set to the path for
48       the debug log to be written.  If set to "stdout" then the debug will go
49       there. Also, you can specify a filehandle that already exists by using
50       debugfh.
51
52       debuglevel determines the amount of debug to generate.  0 is the least,
53       1 is a little more, N is the limit you want.
54
55       debugtime determines wether a timestamp should be preappended to the
56       entry.  style defines the way the data structure is returned.  The two
57       available styles are:
58
59         tree - L<XML::Parser> Tree format
60         node - L<XML::Stream::Node> format
61
62       For more information see the respective man pages.
63
64   Listen
65       Starts the stream by listening on a port for someone to connect, and
66       send the opening stream tag, and then sending a response based on if
67       the received header was correct for this stream.  Server name, port,
68       and namespace are required otherwise we don't know where to listen and
69       what namespace to accept.
70
71   ConnectionAccept
72       Accept an incoming connection.
73
74   Respond
75       If this is a listening socket then we need to respond to the opening
76       <stream:stream/>.
77
78   Connect
79       Starts the stream by connecting to the server, sending the opening
80       stream tag, and then waiting for a response and verifying that it is
81       correct for this stream.  Server name, port, and namespace are required
82       otherwise we don't know where to send the stream to...
83
84         Connect(hostname=>string,
85                 port=>integer,
86                 to=>string,
87                 from=>string,
88                 myhostname=>string,
89                 namespace=>string,
90                 namespaces=>array,
91                 connectiontype=>string,
92                 ssl=>0|1,
93                 ssl_verify =>0x00|0x01|0x02|0x04,
94                 ssl_ca_path=>string,
95                 srv=>string)
96
97       Opens a tcp connection to the specified server and sends the proper
98       opening XML Stream tag.  "hostname", "port", and "namespace" are
99       required.  namespaces allows you to use XML::Stream::Namespace objects.
100
101       "to" is needed if you want the stream to attribute to be something
102       other than the hostname you are connecting to.
103
104       "from" is needed if you want the stream from attribute to be something
105       other than the hostname you are connecting from.
106
107       "myhostname" should not be needed but if the module cannot determine
108       your hostname properly (check the debug log), set this to the correct
109       value, or if you want the other side of the  stream to think that you
110       are someone else.  The type determines the kind of connection that is
111       made:
112
113         "tcpip"    - TCP/IP (default)
114         "stdinout" - STDIN/STDOUT
115         "http"     - HTTP
116
117       HTTP recognizes proxies if the ENV variables http_proxy or https_proxy
118       are set.
119
120       "ssl" specifies whether an SSL socket should be used for encrypted co-
121       mmunications.
122
123       "ssl_verify" determines whether peer certificate verification takes
124       place.  See the documentation for the SSL_verify_mode parameter to
125       IO::Socket::SSL-new()|IO::Socket::SSL>.  The default value is 0x01
126       causing the server certificate to be verified, and requiring that
127       ssl_ca_path be set.
128
129       "ssl_ca_path" should be set to the path to either a directory
130       containing hashed CA certificates, or a single file containing
131       acceptable CA certifictes concatenated together. This parameter is
132       required if ssl_verify is set to anything other than 0x00 (no
133       verification).
134
135       If srv is specified AND Net::DNS is installed and can be loaded, then
136       an SRV query is sent to srv.hostname and the results processed to
137       replace the hostname and port.  If the lookup fails, or Net::DNS cannot
138       be loaded, then hostname and port are left alone as the defaults.
139
140       This function returns the same hash from GetRoot() below. Make sure you
141       get the SID (Session ID) since you have to use it to call most other
142       functions in here.
143
144   OpenStream
145       Send the opening stream and save the root element info.
146
147   OpenFile
148       Starts the stream by opening a file and setting it up so that Process
149       reads from the filehandle to get the incoming stream.
150
151        OpenFile(string)
152
153       Opens a filehandle to the argument specified, and pretends that it is a
154       stream.  It will ignore the outer tag, and not check if it was a
155       <stream:stream/>. This is useful for writing a program that has to
156       parse any XML file that is basically made up of small packets (like
157       RDF).
158
159   Disconnect
160       Sends the closing XML tag and shuts down the socket.
161
162         Disconnect(sid)
163
164       Sends the proper closing XML tag and closes the specified socket down.
165
166   InitConnection
167       Initialize the connection data structure
168
169   ParseStream
170       Takes the incoming stream and makes sure that only full XML tags gets
171       passed to the parser.  If a full tag has not read yet, then the Stream
172       saves the incomplete part and sends the rest to the parser.
173
174   Process
175       Checks for data on the socket and returns a status code depending on if
176       there was data or not.  If a timeout is not defined in the call then
177       the timeout defined in Connect() is used.  If a timeout of 0 is used
178       then the call blocks until it gets some data, otherwise it returns
179       after the timeout period.
180
181         Process(integer)
182
183       Waits for data to be available on the socket.  If a timeout is
184       specified then the Process function waits that period of time before
185       returning nothing.  If a timeout period is not specified then the
186       function blocks until data is received.  The function returns a hash
187       with session ids as the key, and status values or data as the hash
188       values.
189
190   Read
191       Takes the data from the server and returns a string
192
193   Send
194       Takes the data string and sends it to the server
195
196         Send(sid, string);
197
198       Sends the string over the specified connection as is.  This does no
199       checking if valid XML was sent or not.  Best behavior when sending
200       information.
201
202   ProcessStreamFeatures
203       Process the <stream:featutres/> block.
204
205   GetStreamFeature
206       Return the value of the stream feature (if any).
207
208   ReceivedStreamFeatures
209       Have we received the stream:features yet?
210
211   ProcessTLSPacket
212       Process a TLS based packet.
213
214   StartTLS
215       Client function to have the socket start TLS.
216
217   TLSStartTLS
218       Send a <starttls/> in the TLS namespace.
219
220   TLSClientProceed
221       Handle a <proceed/> packet.
222
223   TLSClientSecure
224       Return 1 if the socket is secure, 0 otherwise.
225
226   TLSClientDone
227       Return 1 if the TLS process is done
228
229   TLSClientError
230       return the TLS error if any
231
232   TLSClientFailure
233       Handle a <failure/>
234
235   TLSFailure
236       Send a <failure/> in the TLS namespace
237
238   ProcessSASLPacket
239       Process a SASL based packet.
240
241   SASLAnswerChallenge
242       When we get a <challenge/> we need to do the grunt work to return a
243       <response/>.
244
245   SASLAuth
246       Send an <auth/> in the SASL namespace
247
248   SASLChallenge
249       Send a <challenge/> in the SASL namespace
250
251   SASLClient
252       This is a helper function to perform all of the required steps for
253       doing SASL with the server.
254
255   SASLClientAuthed
256       Return 1 if we authed via SASL, 0 otherwise
257
258   SASLClientDone
259       Return 1 if the SASL process is finished
260
261   SASLClientError
262       Return the error if any
263
264   SASLClientFailure
265       Handle a received <failure/>
266
267   SASLClientSuccess
268       handle a received <success/>
269
270   SASLFailure
271       Send a <failure/> tag in the SASL namespace
272
273   SASLResponse
274       Send a <response/> tag in the SASL namespace
275
276   GetErrorCode
277       if you are returned an undef, you can call this function and hopefully
278       learn more information about the problem.
279
280         GetErrorCode(sid)
281
282       returns a string for the specified session that will hopefully contain
283       some useful information about why Process or Connect returned an undef
284       to you.
285
286   StreamError
287       Given a type and text, generate a <stream:error/> packet to send back
288       to the other side.
289
290   SetXMLData
291       Takes a host of arguments and sets a portion of the specified data
292       strucure with that data.  The function works in two modes "single" or
293       "multiple".  "single" denotes that the function should locate the
294       current tag that matches this data and overwrite it's contents with
295       data passed in.  "multiple" denotes that a new tag should be created
296       even if others exist.
297
298       type    - single or multiple XMLTree - pointer to XML::Stream data
299       object (tree or node) tag     - name of tag to create/modify (if blank
300       assumes
301                 working with top level tag) data    - CDATA to set for tag
302       attribs - attributes to ADD to tag
303
304   GetXMLData
305       Takes a host of arguments and returns various data structures that
306       match them.
307
308       type "existence" - returns 1 or 0 if the tag exists in the top level.
309
310       "value" - returns either the CDATA of the tag, or the value of the
311       attribute depending on which is sought.  This ignores any mark ups to
312       the data and just returns the raw CDATA.
313
314       "value array" returns an array of strings representing all of the CDATA
315       in the specified tag.  This ignores any mark ups to the data and just
316       returns the raw CDATA.
317
318       "tree" - returns a data structure that represents the XML with the
319       specified tag as the root tag.  Depends on the format that you are
320       working with.
321
322       "tree array" returns an array of data structures each with the
323       specified tag as the root tag.
324
325       "child array" - returns a list of all children nodes
326                       not including CDATA nodes.
327
328       "attribs" - returns a hash with the attributes, and
329                   their values, for the things that match
330                   the parameters
331
332       "count" - returns the number of things that match
333                 the arguments
334
335       "tag" - returns the root tag of this tree
336
337       XMLTree - pointer to XML::Stream data structure
338
339       "tag"  - tag to pull data from.  If blank then the top level
340                 tag is accessed.  "attrib"  - attribute value to retrieve.
341       Ignored for types
342                 "value array", "tree", "tree array".  If paired
343                 with value can be used to filter tags based on
344                 attributes and values.  "value"   - only valid if an
345       attribute is supplied.  Used to
346                 filter for tags that only contain this attribute.
347                 Useful to search through multiple tags that all
348                 reference different name spaces.
349
350   XPath
351       Run an xpath query on a node and return back the result.
352
353       XPath(node,path) returns an array of results that match the xpath.
354       node can be any of the three types (Tree, Node).
355
356   XPathCheck
357       Run an xpath query on a node and return 1 or 0 if the path is valid.
358
359   XML2Config
360       Takes an XML data tree and turns it into a hash of hashes.  This only
361       works for certain kinds of XML trees like this:
362
363                       <foo>
364                         <bar>1</bar>
365                         <x>
366                           <y>foo</y>
367                         </x>
368                         <z>5</z>
369                         <z>6</z>
370                       </foo>
371
372       The resulting hash would be:
373
374                       $hash{bar} = 1;
375                       $hash{x}->{y} = "foo";
376                       $hash{z}->[0] = 5;
377                       $hash{z}->[1] = 6;
378
379       Good for config files.
380
381   Config2XML
382       Takes a hash and produces an XML string from it.  If the hash looks
383       like this:
384
385                       $hash{bar} = 1;
386                       $hash{x}->{y} = "foo";
387                       $hash{z}->[0] = 5;
388                       $hash{z}->[1] = 6;
389
390       The resulting xml would be:
391
392                       <foo>
393                         <bar>1</bar>
394                         <x>
395                           <y>foo</y>
396                         </x>
397                         <z>5</z>
398                         <z>6</z>
399                       </foo>
400
401       Good for config files.
402
403   EscapeXML
404       Simple function to make sure that no bad characters make it into in the
405       XML string that might cause the string to be misinterpreted.
406
407   UnescapeXML
408       Simple function to take an escaped string and return it to normal.
409
410   BuildXML
411       Takes one of the data formats that XML::Stream supports and call the
412       proper BuildXML_xxx function on it.
413
414   ConstXMLNS
415       Return the namespace from the constant string.
416
417   GetRoot
418       Returns the hash of attributes for the root <stream:stream/> tag so
419       that any attributes returned can be accessed.  from and any
420       xmlns:foobar might be important.
421
422         GetRoot(sid)
423
424       Returns the attributes that the stream:stream tag sent by the other end
425       listed in a hash for the specified session.
426
427   GetSock
428       returns the Socket so that an outside function can access it if
429       desired.
430
431         GetSock(sid)
432
433       Returns a pointer to the IO::Socket object for the specified session.
434
435   NewSID
436       Returns a session ID to send to an incoming stream in the return
437       header.  By default it just increments a counter and returns that, or
438       you can define a function and set it using the SetCallBacks function.
439
440   SetCallBacks
441       Takes a hash with top level tags to look for as the keys and pointers
442       to functions as the values.
443
444         SetCallBacks(node=>function, update=>function);
445
446       Sets the callback that should be called in various situations.
447
448       "node" is used to handle the data structures that are built for each
449       top level tag.  "update" is used for when Process is blocking waiting
450       for data, but you want your original code to be updated.
451

VARIABLES

453         $NONBLOCKING
454
455       Tells the Parser to enter into a nonblocking state.  This might cause
456       some funky behavior since you can get nested callbacks while things are
457       waiting.  1=on, 0=off(default).
458

EXAMPLES

460       simple example
461
462         use XML::Stream qw( Tree );
463
464         $stream = XML::Stream->new;
465
466         my $status = $stream->Connect(hostname => "jabber.org",
467                                       port => 5222,
468                                       namespace => "jabber:client");
469
470         if (!defined($status)) {
471           print "ERROR: Could not connect to server\n";
472           print "       (",$stream->GetErrorCode(),")\n";
473           exit(0);
474         }
475
476         while($node = $stream->Process()) {
477           # do something with $node
478         }
479
480         $stream->Disconnect();
481
482       Example using a handler
483
484         use XML::Stream qw( Tree );
485
486         $stream = XML::Stream->new;
487         $stream->SetCallBacks(node=>\&noder);
488         $stream->Connect(hostname => "jabber.org",
489                          port => 5222,
490                          namespace => "jabber:client",
491                          timeout => undef) || die $!;
492
493         # Blocks here forever, noder is called for incoming
494         # packets when they arrive.
495         while(defined($stream->Process())) { }
496
497         print "ERROR: Stream died (",$stream->GetErrorCode(),")\n";
498
499         sub noder
500         {
501           my $sid = shift;
502           my $node = shift;
503           # do something with $node
504         }
505

AUTHOR

507       Tweaked, tuned, and brightness changes by Ryan Eatmon, reatmon@ti.com
508       in May of 2000.  Colorized, and Dolby Surround sound added by Thomas
509       Charron, tcharron@jabber.org By Jeremie in October of 1999 for
510       http://etherx.jabber.org/streams/
511
512       Currently maintained by Darian Anthony Patrick.
513
515       Copyright (C) 1998-2004 Jabber Software Foundation http://jabber.org/
516
517       This module licensed under the LGPL, version 2.1.
518
519
520
521perl v5.36.0                      2023-01-20                    XML::Stream(3)
Impressum