Linux Certif

Toute la documentation sur la certification Linux LPI

XML::Stream.3pm

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.

  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.

METHODS

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

VARIABLES

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

EXAMPLES

  ##########################

  # 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

  }

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.