Stream(3)

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

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|N,     written.  If set to "stdout" then the debug
      debugtime=>0|1,        will go there.   Also, you can specify a
      style=>string)         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
                               hash - XML::Stream::Hash 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.
          namespaced=>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
                                    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.
  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.
  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() - 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.