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 
        myhostname=>string,       opening XML Stream tag.  hostname, 
        namespace=>array,         port, and namespace are required.  
        namespaces=>array,        namespaces allows you to use 
        connectiontype=>string)   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.  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.

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.