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 of an XML::Parser::Tree object. After
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|2, written. If set to "stdout" then the debug
debugtime=>0|1) will go there. Also, you can specify a
filehandle that already exists byt using
debugfh. debuglevel determines the amount of
debug to generate. 0 is the least, 2 is the
most. debugtime determines wether a timestamp
should be preappended to the entry.
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
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
Disconnect() - sends the proper closing XML tag and closes the 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.* DEPRECATED * OnNode(function pointer) - This function is deprecated and will be * removed in a future version. Instead, use * the SetCallBacks(node=>function) to do the * same thing...
SetCallBacks(node=>function, - sets the callback that should be
update=>function) called in various situations. node
is used to handle the XML::Parser::Tree
trees 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() - returns the attributes that the stream:stream tag sent by
the other end listed in a hash.
GetSock() - returns a pointer to the IO::Socket object.
Send(string) - sends the string over the connection as is. This
does no checking if valid XML was sent or not. Best
behavior when sending information.
GetErrorCode() - returns a string that will hopefully contain some
useful information about why Process or Connect
returned an undef to you.EXAMPLES
##########################
# simple example
use XML::Stream;
$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;
$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 $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.