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