XML::Stream - Creates and XML Stream connection and parses return data

  XML::Stream is an attempt at solidifying the use of XML via streaming.

  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 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.

  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
          srv=>string)              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
                                      "http"     - HTTP
                                    HTTP recognizes proxies if the ENV
                                    variables http_proxy or https_proxy
                                    are set.  ssl specifies if an SLL
                                    socket should be used for encrypted
                                    communications.  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.

                                    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.

  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).

  $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).

  ##########################
  # 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
  }

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/

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.