NAME
XML::Stream - Creates an 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://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.METHODS
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
ssl_verify to. from is needed if you want the
=>0x00|0x01|0x02|0x04, stream from attribute to be something
ssl_ca_path=>string, other than the hostname you are
srv=>string) 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 whether an SSL socket
should be used for encrypted co-
mmunications.
ssl_verify determines whether peer
certificate verification takes place.
See the documentation for the
SSL_verify_mode parameter to
L<IO::Socket::SSL->new()|IO::Socket::SSL>.
The default value is 0x01 causing the
server certificate to be verified, and
requiring that ssl_ca_path be set.
ssl_ca_path should be set to the path to
either a directory containing hashed CA
certificates, or a single file containing
acceptable CA certifictes concatenated
together. This parameter is required if
ssl_verify is set to anything other than
0x00 (no verification).
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.
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.
XPath(node,path) - returns an array of results that match the xpath.
node can be any of the three types (Tree, Node).VARIABLES
$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).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/
Currently maintained by Darian Anthony Patrick.
COPYRIGHT
Copyright (C) 1998-2004 Jabber Software Foundation http://jabber.org/
This module licensed under the LGPL, version 2.1.