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 
          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.
          namespaced=>array,        to is needed if you want the stream
          connectiontype=>string)   to attribute to be something other
                                    than the hostname you are connecting
                                    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

  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.

* DEPRECATED * OnNode(function pointer) - This function is deprecated and will be * removed in a future version. Instead, use * the SetCallBacks(node=>function) to do the * same thing...

  SetCallBacks(node=>function,   - sets the callback that should be
               update=>function)   called in various situations.  node
                                   is used to handle the XML::Parser::Tree
                                   trees 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() - 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->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 $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.