XML::Stream (3pm)

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

This module provides the user with methods to connect to a remote server, send a stream of XML to the server, and receive/parse an XML stream from the server. It is primarily based work for the Etherx XML router developed by the Jabber Development Team. For more information about this project visit http://xmpp.org/protocols/streams/.

XML::Stream gives the user the ability to define a central callback that will be used to handle the tags received from the server. These tags are passed in the format defined at instantiation time. the closing tag of an object is seen, the tree is finished and passed to the call back function. What the user does with it from there is up to them.

For a detailed description of how this module works, and about the data structure that it returns, please view the source of Stream.pm and look at the detailed description at the end of the file.

NOTE: The parser that XML::Stream::Parser provides, as are most Perl parsers, is synchronous. If you are in the middle of parsing a packet and call a user defined callback, the Parser is blocked until your callback finishes. This means you cannot be operating on a packet, send out another packet and wait for a response to that packet. It will never get to you. Threading might solve this, but as we all know threading in Perl is not quite up to par yet. This issue will be revisted in the future.

new(debug=>string, - creates the XML::Stream object. debug debugfh=>FileHandle, should be set to the path for the debug log debuglevel=>0|1|N, to be written. If set to "stdout" then the debugtime=>0|1, debug will go there. Also, you can specify style=>string) a filehandle that already exists byt using debugfh. debuglevel determines the amount of debug to generate. 0 is the least, 1 is a little more, N is the limit you want. debugtime determines wether a timestamp should be preappended to the entry. style defines the way the data structure is returned. The two available styles are:

tree - XML::Parser Tree format node - XML::Stream::Node format

For more information see the respective man pages.

Connect(hostname=>string, - opens a tcp connection to the port=>integer, specified server and sends the proper to=>string, opening XML Stream tag. hostname, from=>string, port, and namespace are required. myhostname=>string, namespaces allows you to use namespace=>string, XML::Stream::Namespace objects. namespaces=>array, to is needed if you want the stream connectiontype=>string, to attribute to be something other ssl=>0|1, than the hostname you are connecting srv=>string) to. from is needed if you want the stream from attribute to be something other than the hostname you are connecting from. myhostname should not be needed but if the module cannot determine your hostname properly (check the debug log), set this to the correct value, or if you want the other side of the stream to think that you are someone else. The type determines the kind of connection that is made: "tcpip" - TCP/IP (default) "stdinout" - STDIN/STDOUT "http" - HTTP HTTP recognizes proxies if the ENV variables http_proxy or https_proxy are set. ssl specifies if an SSL socket should be used for encrypted communications. This function returns the same hash from GetRoot() below. Make sure you get the SID (Session ID) since you have to use it to call most other functions in here.

If srv is specified AND Net::DNS is installed and can be loaded, then an SRV query is sent to srv.hostname and the results processed to replace the hostname and port. If the lookup fails, or Net::DNS cannot be loaded, then hostname and port are left alone as the defaults.

OpenFile(string) - opens a filehandle to the argument specified, and pretends that it is a stream. It will ignore the outer tag, and not check if it was a <stream:stream/>. This is useful for writing a program that has to parse any XML file that is basically made up of small packets (like RDF).

Disconnect(sid) - sends the proper closing XML tag and closes the specified socket down.

Process(integer) - waits for data to be available on the socket. If a timeout is specified then the Process function waits that period of time before returning nothing. If a timeout period is not specified then the function blocks until data is received. The function returns a hash with session ids as the key, and status values or data as the hash values.

SetCallBacks(node=>function, - sets the callback that should be update=>function) called in various situations. node is used to handle the data structures that are built for each top level tag. Update is used for when Process is blocking waiting for data, but you want your original code to be updated.

GetRoot(sid) - returns the attributes that the stream:stream tag sent by the other end listed in a hash for the specified session.

GetSock(sid) - returns a pointer to the IO::Socket object for the specified session.

Send(sid, - sends the string over the specified connection as is. string) This does no checking if valid XML was sent or not. Best behavior when sending information.

GetErrorCode(sid) - returns a string for the specified session that will hopefully contain some useful information about why Process or Connect returned an undef to you.

XPath(node,path) - returns an array of results that match the xpath. node can be any of the three types (Tree, Node).

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

########################## # simple example

use XML::Stream qw( Tree );

$stream = new XML::Stream;

my $status = $stream->Connect(hostname => "jabber.org", port => 5222, namespace => "jabber:client");

if (!defined($status)) { print "ERROR: Could not connect to server\n"; print " (",$stream->GetErrorCode(),")\n"; exit(0); }

while($node = $stream->Process()) { # do something with $node }

$stream->Disconnect();

########################### # example using a handler

use XML::Stream qw( Tree );

$stream = new XML::Stream; $stream->SetCallBacks(node=>\&noder); $stream->Connect(hostname => "jabber.org", port => 5222, namespace => "jabber:client", timeout => undef) || die $!;

# Blocks here forever, noder is called for incoming # packets when they arrive. while(defined($stream->Process())) { }

print "ERROR: Stream died (",$stream->GetErrorCode(),")\n";

sub noder { my $sid = shift; my $node = shift; # do something with $node }

Tweaked, tuned, and brightness changes by Ryan Eatmon, [email protected] in May of 2000. Colorized, and Dolby Surround sound added by Thomas Charron, [email protected] By Jeremie in October of 1999 for http://etherx.jabber.org/streams/

Currently maintained by Darian Anthony Patrick.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.