1XML::Stream(3) User Contributed Perl Documentation XML::Stream(3)
2
6 XML::Stream - Creates and 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://etherx.jabber.org/stream/.
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.
21 the closing tag of an object is seen, the tree is finished and passed
22 to the call back function. What the user does with it from there is up
23 to 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
27 look 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
31 packet and call a user defined callback, the Parser is blocked until
32 your callback finishes. This means you cannot be operating on a
33 packet, send out another packet and wait for a response to that packet.
34 It will never get to you. Threading might solve this, but as we all
35 know threading in Perl is not quite up to par yet. This issue will be
36 revisted in the future.
37
39 new(debug=>string, - creates the XML::Stream object. debug
40 debugfh=>FileHandle, should be set to the path for the debug log
41 debuglevel=>0⎪1⎪N, to be written. If set to "stdout" then the
42 debugtime=>0⎪1, debug will go there. Also, you can specify
43 style=>string) a filehandle that already exists byt using
44 debugfh. debuglevel determines the amount
45 of debug to generate. 0 is the least, 1 is
46 a little more, N is the limit you want.
47 debugtime determines wether a timestamp
48 should be preappended to the entry. style
49 defines the way the data structure is
50 returned. The two available styles are:
51 tree - XML::Parser Tree format
53 node - XML::Stream::Node format
54 For more information see the respective man
56 pages.
57 Connect(hostname=>string, - opens a tcp connection to the
59 port=>integer, specified server and sends the proper
60 to=>string, opening XML Stream tag. hostname,
61 from=>string, port, and namespace are required.
62 myhostname=>string, namespaces allows you to use
63 namespace=>string, XML::Stream::Namespace objects.
64 namespaces=>array, to is needed if you want the stream
65 connectiontype=>string, to attribute to be something other
66 ssl=>0⎪1, than the hostname you are connecting
67 srv=>string) to. from is needed if you want the
68 stream from attribute to be something
69 other than the hostname you are
70 connecting from. myhostname should
71 not be needed but if the module
72 cannot determine your hostname
73 properly (check the debug log), set
74 this to the correct value, or if you
75 want the other side of the stream to
76 think that you are someone else. The
77 type determines the kind of
78 connection that is made:
79 "tcpip" - TCP/IP (default)
80 "stdinout" - STDIN/STDOUT
81 "http" - HTTP
82 HTTP recognizes proxies if the ENV
83 variables http_proxy or https_proxy
84 are set. ssl specifies if an SLL
85 socket should be used for encrypted
86 communications. This function
87 returns the same hash from GetRoot()
88 below. Make sure you get the SID
89 (Session ID) since you have to use it
90 to call most other functions in here.
91 If srv is specified AND Net::DNS is
93 installed and can be loaded, then
94 an SRV query is sent to srv.hostname
95 and the results processed to replace
96 the hostname and port. If the lookup
97 fails, or Net::DNS cannot be loaded,
98 then hostname and port are left alone
99 as the defaults.
100 OpenFile(string) - opens a filehandle to the argument specified, and
102 pretends that it is a stream. It will ignore the
103 outer tag, and not check if it was a
104 <stream:stream/>. This is useful for writing a
105 program that has to parse any XML file that is
106 basically made up of small packets (like RDF).
107 Disconnect(sid) - sends the proper closing XML tag and closes the
109 specified socket down.
110 Process(integer) - waits for data to be available on the socket. If
112 a timeout is specified then the Process function
113 waits that period of time before returning nothing.
114 If a timeout period is not specified then the
115 function blocks until data is received. The
116 function returns a hash with session ids as the key,
117 and status values or data as the hash values.
118 SetCallBacks(node=>function, - sets the callback that should be
120 update=>function) called in various situations. node
121 is used to handle the data structures
122 that are built for each top level tag.
123 Update is used for when Process is
124 blocking waiting for data, but you
125 want your original code to be updated.
126 GetRoot(sid) - returns the attributes that the stream:stream tag sent
128 by the other end listed in a hash for the specified
129 session.
130 GetSock(sid) - returns a pointer to the IO::Socket object for the
132 specified session.
133 Send(sid, - sends the string over the specified connection as is.
135 string) This does no checking if valid XML was sent or not.
136 Best behavior when sending information.
137 GetErrorCode(sid) - returns a string for the specified session that
139 will hopefully contain some useful information
140 about why Process or Connect returned an undef
141 to you.
142 XPath(node,path) - returns an array of results that match the xpath.
144 node can be any of the three types (Tree, Node).
145
147 $NONBLOCKING - tells the Parser to enter into a nonblocking state. This
148 might cause some funky behavior since you can get nested
149 callbacks while things are waiting. 1=on, 0=off(default).
150
152 ##########################
153 # simple example
154 use XML::Stream qw( Tree );
156 $stream = new XML::Stream;
158 my $status = $stream->Connect(hostname => "jabber.org",
160 port => 5222,
161 namespace => "jabber:client");
162 if (!defined($status)) {
164 print "ERROR: Could not connect to server\n";
165 print " (",$stream->GetErrorCode(),")\n";
166 exit(0);
167 }
168 while($node = $stream->Process()) {
170 # do something with $node
171 }
172 $stream->Disconnect();
174 ###########################
176 # example using a handler
177 use XML::Stream qw( Tree );
179 $stream = new XML::Stream;
181 $stream->SetCallBacks(node=>\&noder);
182 $stream->Connect(hostname => "jabber.org",
183 port => 5222,
184 namespace => "jabber:client",
185 timeout => undef) ⎪⎪ die $!;
186 # Blocks here forever, noder is called for incoming
188 # packets when they arrive.
189 while(defined($stream->Process())) { }
190 print "ERROR: Stream died (",$stream->GetErrorCode(),")\n";
192 sub noder
194 {
195 my $sid = shift;
196 my $node = shift;
197 # do something with $node
198 }
199
201 Tweaked, tuned, and brightness changes by Ryan Eatmon, reatmon@ti.com
202 in May of 2000. Colorized, and Dolby Surround sound added by Thomas
203 Charron, tcharron@jabber.org By Jeremie in October of 1999 for
204 http://etherx.jabber.org/streams/
205
207 This module is free software; you can redistribute it and/or modify it
208 under the same terms as Perl itself.
209perl v5.8.8 2004-04-04 XML::Stream(3)