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
                           written.  If set to "stdout" then the debug
                           will go there.   Also, you can specify a 
                           filehandle that already exists and use that.

Connect(hostname=>string,  - opens a tcp connection to the specified
        port=>integer,       server and sends the proper opening XML
        myhostname=>string,  Stream tag.  hostname, port, and namespace
        namespace=>array,    are required.  namespaces allows you
        namespaces=>array)   to use XML::Stream::Namespace objects.
                             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.

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.

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->OnNode(\&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.