NAME
XML::Stream - Creates and XML Stream connection and parses return data
SYNOPSIS
XML::Stream is an attempt at solidifying the use of XML via streaming.DESCRIPTION
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://etherx.jabber.org/stream/.
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.METHODS
new(debug=>string, - creates the XML::Stream object. debug should
debugfh=>FileHandle, be set to the path for the debug log to be
debuglevel=>0|1|N, written. If set to "stdout" then the debug
debugtime=>0|1, will go there. Also, you can specify a
style=>string) 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
hash - XML::Stream::Hash 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.
namespaced=>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
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 SLL
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.
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.EXAMPLES
##########################
# 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
}AUTHOR
Tweaked, tuned, and brightness changes by Ryan Eatmon, reatmon@ti.com in May of 2000. Colorized, and Dolby Surround sound added by Thomas Charron, tcharron@jabber.org By Jeremie in October of 1999 for http://etherx.jabber.org/streams/
COPYRIGHT
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.