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

Connect(name=>string,      - opens a tcp connection to the specified
        port=>integer,       server and sends the proper opening XML
        namespace=>string)   Stream tag.  All fields are required.

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.

OnNode(function pointer) - sets the callback used to handle the
                           XML::Parser::Tree trees that are built
                           for each top level tag.

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.

EXAMPLES

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

  use XML::Stream;

  $stream = new XML::Stream;

  $stream->Connect(name => "jabber.org", 
                   port => 5222, 
                   namespace => "jabber:client") || die $!;

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

  $stream->Disconnect();


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

  use XML::Stream;

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

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

  $stream->Disconnect();

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

AUTHOR

Tweaked, tuned, and brightness changes by Ryan Eatmon, reatmon@ti.com 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.