1XML::Stream(3) User Contributed Perl Documentation XML::Stream(3)
2
6 XML::Stream - Creates an XML Stream connection and parses return data
7
9 XML::Stream is an attempt at solidifying the use of XML via streaming.
10
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 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 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 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
39 new
40 new(
41 debug => string,
42 debugfh => FileHandle,
43 debuglevel => 0|1|N,
44 debugtime => 0|1,
45 style => string)
46 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 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 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 tree - L<XML::Parser> Tree format
60 node - L<XML::Stream::Node> format
61 For more information see the respective man pages.
63 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 ConnectionAccept
72 Accept an incoming connection.
73 Respond
75 If this is a listening socket then we need to respond to the opening
76 <stream:stream/>.
77 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 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 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 "to" is needed if you want the stream to attribute to be something
102 other than the hostname you are connecting to.
103 "from" is needed if you want the stream from attribute to be something
105 other than the hostname you are connecting from.
106 "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 "tcpip" - TCP/IP (default)
114 "stdinout" - STDIN/STDOUT
115 "http" - HTTP
116 HTTP recognizes proxies if the ENV variables http_proxy or https_proxy
118 are set.
119 "ssl" specifies whether an SSL socket should be used for encrypted co-
121 mmunications.
122 "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 "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 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 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 OpenStream
145 Send the opening stream and save the root element info.
146 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 OpenFile(string)
152 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 Disconnect
160 Sends the closing XML tag and shuts down the socket.
161 Disconnect(sid)
163 Sends the proper closing XML tag and closes the specified socket down.
165 InitConnection
167 Initialize the connection data structure
168 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 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 Process(integer)
182 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 Read
191 Takes the data from the server and returns a string
192 Send
194 Takes the data string and sends it to the server
195 Send(sid, string);
197 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 ProcessStreamFeatures
203 Process the <stream:featutres/> block.
204 GetStreamFeature
206 Return the value of the stream feature (if any).
207 ReceivedStreamFeatures
209 Have we received the stream:features yet?
210 ProcessTLSPacket
212 Process a TLS based packet.
213 StartTLS
215 Client function to have the socket start TLS.
216 TLSStartTLS
218 Send a <starttls/> in the TLS namespace.
219 TLSClientProceed
221 Handle a <proceed/> packet.
222 TLSClientSecure
224 Return 1 if the socket is secure, 0 otherwise.
225 TLSClientDone
227 Return 1 if the TLS process is done
228 TLSClientError
230 return the TLS error if any
231 TLSClientFailure
233 Handle a <failure/>
234 TLSFailure
236 Send a <failure/> in the TLS namespace
237 ProcessSASLPacket
239 Process a SASL based packet.
240 SASLAnswerChallenge
242 When we get a <challenge/> we need to do the grunt work to return a
243 <response/>.
244 SASLAuth
246 Send an <auth/> in the SASL namespace
247 SASLChallenge
249 Send a <challenge/> in the SASL namespace
250 SASLClient
252 This is a helper function to perform all of the required steps for
253 doing SASL with the server.
254 SASLClientAuthed
256 Return 1 if we authed via SASL, 0 otherwise
257 SASLClientDone
259 Return 1 if the SASL process is finished
260 SASLClientError
262 Return the error if any
263 SASLClientFailure
265 Handle a received <failure/>
266 SASLClientSuccess
268 handle a received <success/>
269 SASLFailure
271 Send a <failure/> tag in the SASL namespace
272 SASLResponse
274 Send a <response/> tag in the SASL namespace
275 GetErrorCode
277 if you are returned an undef, you can call this function and hopefully
278 learn more information about the problem.
279 GetErrorCode(sid)
281 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 StreamError
287 Given a type and text, generate a <stream:error/> packet to send back
288 to the other side.
289 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 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 GetXMLData
305 Takes a host of arguments and returns various data structures that
306 match them.
307 type "existence" - returns 1 or 0 if the tag exists in the top level.
309 "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 "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 "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 "tree array" returns an array of data structures each with the
323 specified tag as the root tag.
324 "child array" - returns a list of all children nodes
326 not including CDATA nodes.
327 "attribs" - returns a hash with the attributes, and
329 their values, for the things that match
330 the parameters
331 "count" - returns the number of things that match
333 the arguments
334 "tag" - returns the root tag of this tree
336 XMLTree - pointer to XML::Stream data structure
338 "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 XPath
351 Run an xpath query on a node and return back the result.
352 XPath(node,path) returns an array of results that match the xpath.
354 node can be any of the three types (Tree, Node).
355 XPathCheck
357 Run an xpath query on a node and return 1 or 0 if the path is valid.
358 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 <foo>
364 <bar>1</bar>
365 <x>
366 <y>foo</y>
367 </x>
368 <z>5</z>
369 <z>6</z>
370 </foo>
371 The resulting hash would be:
373 $hash{bar} = 1;
375 $hash{x}->{y} = "foo";
376 $hash{z}->[0] = 5;
377 $hash{z}->[1] = 6;
378 Good for config files.
380 Config2XML
382 Takes a hash and produces an XML string from it. If the hash looks
383 like this:
384 $hash{bar} = 1;
386 $hash{x}->{y} = "foo";
387 $hash{z}->[0] = 5;
388 $hash{z}->[1] = 6;
389 The resulting xml would be:
391 <foo>
393 <bar>1</bar>
394 <x>
395 <y>foo</y>
396 </x>
397 <z>5</z>
398 <z>6</z>
399 </foo>
400 Good for config files.
402 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 UnescapeXML
408 Simple function to take an escaped string and return it to normal.
409 BuildXML
411 Takes one of the data formats that XML::Stream supports and call the
412 proper BuildXML_xxx function on it.
413 ConstXMLNS
415 Return the namespace from the constant string.
416 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 GetRoot(sid)
423 Returns the attributes that the stream:stream tag sent by the other end
425 listed in a hash for the specified session.
426 GetSock
428 returns the Socket so that an outside function can access it if
429 desired.
430 GetSock(sid)
432 Returns a pointer to the IO::Socket object for the specified session.
434 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 SetCallBacks
441 Takes a hash with top level tags to look for as the keys and pointers
442 to functions as the values.
443 SetCallBacks(node=>function, update=>function);
445 Sets the callback that should be called in various situations.
447 "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
453 $NONBLOCKING
454 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
460 simple example
461 use XML::Stream qw( Tree );
463 $stream = XML::Stream->new;
465 my $status = $stream->Connect(hostname => "jabber.org",
467 port => 5222,
468 namespace => "jabber:client");
469 if (!defined($status)) {
471 print "ERROR: Could not connect to server\n";
472 print " (",$stream->GetErrorCode(),")\n";
473 exit(0);
474 }
475 while($node = $stream->Process()) {
477 # do something with $node
478 }
479 $stream->Disconnect();
481 Example using a handler
483 use XML::Stream qw( Tree );
485 $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 # Blocks here forever, noder is called for incoming
494 # packets when they arrive.
495 while(defined($stream->Process())) { }
496 print "ERROR: Stream died (",$stream->GetErrorCode(),")\n";
498 sub noder
500 {
501 my $sid = shift;
502 my $node = shift;
503 # do something with $node
504 }
505
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 Currently maintained by Darian Anthony Patrick.
513
515 Copyright (C) 1998-2004 Jabber Software Foundation http://jabber.org/
516 This module licensed under the LGPL, version 2.1.
518perl v5.36.0 2023-01-20 XML::Stream(3)