XML::Stream(3pm) - phpMan

Command: man perldoc info search(apropos)  


XML::Stream(3pm)               User Contributed Perl Documentation               XML::Stream(3pm)

NAME
       XML::Stream - Creates an 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://xmpp.org/protocols/streams/.

       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
         new(
             debug      => string,
             debugfh    => FileHandle,
             debuglevel => 0|1|N,
             debugtime  => 0|1,
             style      => string)

       Creates the XML::Stream object.  debug should be set to the path for the debug log to be
       written.  If set to "stdout" then the debug will go there. Also, you can specify a
       filehandle that already exists by 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 - L<XML::Parser> Tree format
         node - L<XML::Stream::Node> format

       For more information see the respective man pages.

   Listen
       Starts the stream by listening on a port for someone to connect, and send the opening
       stream tag, and then sending a response based on if the received header was correct for
       this stream.  Server name, port, and namespace are required otherwise we don't know where
       to listen and what namespace to accept.

   ConnectionAccept
       Accept an incoming connection.

   Respond
       If this is a listening socket then we need to respond to the opening <stream:stream/>.

   Connect
       Starts the stream by connecting to the server, sending the opening stream tag, and then
       waiting for a response and verifying that it is correct for this stream.  Server name,
       port, and namespace are required otherwise we don't know where to send the stream to...

         Connect(hostname=>string,
                 port=>integer,
                 to=>string,
                 from=>string,
                 myhostname=>string,
                 namespace=>string,
                 namespaces=>array,
                 connectiontype=>string,
                 ssl=>0|1,
                 ssl_verify =>0x00|0x01|0x02|0x04,
                 ssl_ca_path=>string,
                 srv=>string)

       Opens a tcp connection to the specified server and sends the proper opening XML Stream
       tag.  "hostname", "port", and "namespace" are required.  namespaces allows you to use
       XML::Stream::Namespace objects.

       "to" is needed if you want the stream 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
         "http"     - HTTP

       HTTP recognizes proxies if the ENV variables http_proxy or https_proxy are set.

       "ssl" specifies whether an SSL socket should be used for encrypted co- mmunications.

       "ssl_verify" determines whether peer certificate verification takes place.  See the
       documentation for the SSL_verify_mode parameter to IO::Socket::SSL-new()|IO::Socket::SSL>.
       The default value is 0x01 causing the server certificate to be verified, and requiring
       that ssl_ca_path be set.

       "ssl_ca_path" should be set to the path to either a directory containing hashed CA
       certificates, or a single file containing acceptable CA certifictes concatenated together.
       This parameter is required if ssl_verify is set to anything other than 0x00 (no
       verification).

       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.

       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.

   OpenStream
       Send the opening stream and save the root element info.

   OpenFile
       Starts the stream by opening a file and setting it up so that Process reads from the
       filehandle to get the incoming stream.

        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
       Sends the closing XML tag and shuts down the socket.

         Disconnect(sid)

       Sends the proper closing XML tag and closes the specified socket down.

   InitConnection
       Initialize the connection data structure

   ParseStream
       Takes the incoming stream and makes sure that only full XML tags gets passed to the
       parser.  If a full tag has not read yet, then the Stream saves the incomplete part and
       sends the rest to the parser.

   Process
       Checks for data on the socket and returns a status code depending on if there was data or
       not.  If a timeout is not defined in the call then the timeout defined in Connect() is
       used.  If a timeout of 0 is used then the call blocks until it gets some data, otherwise
       it returns after the timeout period.

         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.

   Read
       Takes the data from the server and returns a string

   Send
       Takes the data string and sends it to the server

         Send(sid, string);

       Sends the string over the specified connection as is.  This does no checking if valid XML
       was sent or not.  Best behavior when sending information.

   ProcessStreamFeatures
       Process the <stream:featutres/> block.

   GetStreamFeature
       Return the value of the stream feature (if any).

   ReceivedStreamFeatures
       Have we received the stream:features yet?

   ProcessTLSPacket
       Process a TLS based packet.

   StartTLS
       Client function to have the socket start TLS.

   TLSStartTLS
       Send a <starttls/> in the TLS namespace.

   TLSClientProceed
       Handle a <proceed/> packet.

   TLSClientSecure
       Return 1 if the socket is secure, 0 otherwise.

   TLSClientDone
       Return 1 if the TLS process is done

   TLSClientError
       return the TLS error if any

   TLSClientFailure
       Handle a <failure/>

   TLSFailure
       Send a <failure/> in the TLS namespace

   ProcessSASLPacket
       Process a SASL based packet.

   SASLAnswerChallenge
       When we get a <challenge/> we need to do the grunt work to return a <response/>.

   SASLAuth
       Send an <auth/> in the SASL namespace

   SASLChallenge
       Send a <challenge/> in the SASL namespace

   SASLClient
       This is a helper function to perform all of the required steps for doing SASL with the
       server.

   SASLClientAuthed
       Return 1 if we authed via SASL, 0 otherwise

   SASLClientDone
       Return 1 if the SASL process is finished

   SASLClientError
       Return the error if any

   SASLClientFailure
       Handle a received <failure/>

   SASLClientSuccess
       handle a received <success/>

   SASLFailure
       Send a <failure/> tag in the SASL namespace

   SASLResponse
       Send a <response/> tag in the SASL namespace

   GetErrorCode
       if you are returned an undef, you can call this function and hopefully learn more
       information about the problem.

         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.

   StreamError
       Given a type and text, generate a <stream:error/> packet to send back to the other side.

   SetXMLData
       Takes a host of arguments and sets a portion of the specified data strucure with that
       data.  The function works in two modes "single" or "multiple".  "single" denotes that the
       function should locate the current tag that matches this data and overwrite it's contents
       with data passed in.  "multiple" denotes that a new tag should be created even if others
       exist.

       type    - single or multiple XMLTree - pointer to XML::Stream data object (tree or node)
       tag     - name of tag to create/modify (if blank assumes
                 working with top level tag) data    - CDATA to set for tag attribs - attributes
       to ADD to tag

   GetXMLData
       Takes a host of arguments and returns various data structures that match them.

       type "existence" - returns 1 or 0 if the tag exists in the top level.

       "value" - returns either the CDATA of the tag, or the value of the attribute depending on
       which is sought.  This ignores any mark ups to the data and just returns the raw CDATA.

       "value array" returns an array of strings representing all of the CDATA in the specified
       tag.  This ignores any mark ups to the data and just returns the raw CDATA.

       "tree" - returns a data structure that represents the XML with the specified tag as the
       root tag.  Depends on the format that you are working with.

       "tree array" returns an array of data structures each with the specified tag as the root
       tag.

       "child array" - returns a list of all children nodes
                       not including CDATA nodes.

       "attribs" - returns a hash with the attributes, and
                   their values, for the things that match
                   the parameters

       "count" - returns the number of things that match
                 the arguments

       "tag" - returns the root tag of this tree

       XMLTree - pointer to XML::Stream data structure

       "tag"  - tag to pull data from.  If blank then the top level
                 tag is accessed.  "attrib"  - attribute value to retrieve.  Ignored for types
                 "value array", "tree", "tree array".  If paired
                 with value can be used to filter tags based on
                 attributes and values.  "value"   - only valid if an attribute is supplied.
       Used to
                 filter for tags that only contain this attribute.
                 Useful to search through multiple tags that all
                 reference different name spaces.

   XPath
       Run an xpath query on a node and return back the result.

       XPath(node,path) returns an array of results that match the xpath.  node can be any of the
       three types (Tree, Node).

   XPathCheck
       Run an xpath query on a node and return 1 or 0 if the path is valid.

   XML2Config
       Takes an XML data tree and turns it into a hash of hashes.  This only works for certain
       kinds of XML trees like this:

                       <foo>
                         <bar>1</bar>
                         <x>
                           <y>foo</y>
                         </x>
                         <z>5</z>
                         <z>6</z>
                       </foo>

       The resulting hash would be:

                       $hash{bar} = 1;
                       $hash{x}->{y} = "foo";
                       $hash{z}->[0] = 5;
                       $hash{z}->[1] = 6;

       Good for config files.

   Config2XML
       Takes a hash and produces an XML string from it.  If the hash looks like this:

                       $hash{bar} = 1;
                       $hash{x}->{y} = "foo";
                       $hash{z}->[0] = 5;
                       $hash{z}->[1] = 6;

       The resulting xml would be:

                       <foo>
                         <bar>1</bar>
                         <x>
                           <y>foo</y>
                         </x>
                         <z>5</z>
                         <z>6</z>
                       </foo>

       Good for config files.

   EscapeXML
       Simple function to make sure that no bad characters make it into in the XML string that
       might cause the string to be misinterpreted.

   UnescapeXML
       Simple function to take an escaped string and return it to normal.

   BuildXML
       Takes one of the data formats that XML::Stream supports and call the proper BuildXML_xxx
       function on it.

   ConstXMLNS
       Return the namespace from the constant string.

   GetRoot
       Returns the hash of attributes for the root <stream:stream/> tag so that any attributes
       returned can be accessed.  from and any xmlns:foobar might be important.

         GetRoot(sid)

       Returns the attributes that the stream:stream tag sent by the other end listed in a hash
       for the specified session.

   GetSock
       returns the Socket so that an outside function can access it if desired.

         GetSock(sid)

       Returns a pointer to the IO::Socket object for the specified session.

   NewSID
       Returns a session ID to send to an incoming stream in the return header.  By default it
       just increments a counter and returns that, or you can define a function and set it using
       the SetCallBacks function.

   SetCallBacks
       Takes a hash with top level tags to look for as the keys and pointers to functions as the
       values.

         SetCallBacks(node=>function, update=>function);

       Sets the callback that should be 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.

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 = XML::Stream->new;

         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 = XML::Stream->new;
         $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 AT ti.com in May of 2000.
       Colorized, and Dolby Surround sound added by Thomas Charron, tcharron AT jabber.org By
       Jeremie in October of 1999 for http://etherx.jabber.org/streams/

       Currently maintained by Darian Anthony Patrick.

COPYRIGHT
       Copyright (C) 1998-2004 Jabber Software Foundation http://jabber.org/

       This module licensed under the LGPL, version 2.1.

perl v5.32.0                                2021-01-20                           XML::Stream(3pm)

Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2024-10-04 13:19 @98.84.18.52 CrawledBy CCBot/2.0 (https://commoncrawl.org/faq/)
Valid XHTML 1.0!Valid CSS!