{ "content": [ { "type": "text", "text": "# XML::Stream (perldoc)\n\n## NAME\n\nXML::Stream - Creates an XML Stream connection and parses return data\n\n## SYNOPSIS\n\nXML::Stream is an attempt at solidifying the use of XML via streaming.\n\n## DESCRIPTION\n\nThis module provides the user with methods to connect to a remote server, send a stream of XML\nto the server, and receive/parse an XML stream from the server. It is primarily based work for\nthe Etherx XML router developed by the Jabber Development Team. For more information about this\nproject visit http://xmpp.org/protocols/streams/.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS** (31 subsections)\n- **VARIABLES**\n- **EXAMPLES**\n- **AUTHOR**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "XML::Stream", "section": "", "mode": "perldoc", "summary": "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.", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "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" ], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 21, "subsections": [] }, { "name": "METHODS", "lines": 23, "subsections": [ { "name": "Listen", "lines": 5 }, { "name": "ConnectionAccept", "lines": 2 }, { "name": "Respond", "lines": 2 }, { "name": "Connect", "lines": 55 }, { "name": "OpenStream", "lines": 2 }, { "name": "OpenFile", "lines": 9 }, { "name": "Disconnect", "lines": 6 }, { "name": "InitConnection", "lines": 2 }, { "name": "ParseStream", "lines": 4 }, { "name": "Process", "lines": 12 }, { "name": "Read", "lines": 2 }, { "name": "Send", "lines": 7 }, { "name": "ProcessStreamFeatures", "lines": 2 }, { "name": "GetStreamFeature", "lines": 2 }, { "name": "ReceivedStreamFeatures", "lines": 2 }, { "name": "ProcessTLSPacket", "lines": 2 }, { "name": "StartTLS", "lines": 23 }, { "name": "ProcessSASLPacket", "lines": 35 }, { "name": "GetErrorCode", "lines": 8 }, { "name": "StreamError", "lines": 2 }, { "name": "SetXMLData", "lines": 9 }, { "name": "GetXMLData", "lines": 63 }, { "name": "Config2XML", "lines": 20 }, { "name": "EscapeXML", "lines": 3 }, { "name": "UnescapeXML", "lines": 2 }, { "name": "BuildXML", "lines": 3 }, { "name": "ConstXMLNS", "lines": 2 }, { "name": "GetRoot", "lines": 8 }, { "name": "GetSock", "lines": 6 }, { "name": "NewSID", "lines": 4 }, { "name": "SetCallBacks", "lines": 11 } ] }, { "name": "VARIABLES", "lines": 5, "subsections": [] }, { "name": "EXAMPLES", "lines": 46, "subsections": [] }, { "name": "AUTHOR", "lines": 6, "subsections": [] }, { "name": "COPYRIGHT", "lines": 4, "subsections": [] } ], "sections": { "NAME": { "content": "XML::Stream - Creates an XML Stream connection and parses return data\n", "subsections": [] }, "SYNOPSIS": { "content": "XML::Stream is an attempt at solidifying the use of XML via streaming.\n", "subsections": [] }, "DESCRIPTION": { "content": "This module provides the user with methods to connect to a remote server, send a stream of XML\nto the server, and receive/parse an XML stream from the server. It is primarily based work for\nthe Etherx XML router developed by the Jabber Development Team. For more information about this\nproject visit http://xmpp.org/protocols/streams/.\n\nXML::Stream gives the user the ability to define a central callback that will be used to handle\nthe tags received from the server. These tags are passed in the format defined at instantiation\ntime. the closing tag of an object is seen, the tree is finished and passed to the call back\nfunction. What the user does with it from there is up to them.\n\nFor a detailed description of how this module works, and about the data structure that it\nreturns, please view the source of Stream.pm and look at the detailed description at the end of\nthe file.\n\nNOTE: The parser that XML::Stream::Parser provides, as are most Perl parsers, is synchronous. If\nyou are in the middle of parsing a packet and call a user defined callback, the Parser is\nblocked until your callback finishes. This means you cannot be operating on a packet, send out\nanother packet and wait for a response to that packet. It will never get to you. Threading might\nsolve this, but as we all know threading in Perl is not quite up to par yet. This issue will be\nrevisted in the future.\n", "subsections": [] }, "METHODS": { "content": "new\nnew(\ndebug => string,\ndebugfh => FileHandle,\ndebuglevel => 0|1|N,\ndebugtime => 0|1,\nstyle => string)\n\nCreates the XML::Stream object. debug should be set to the path for the debug log to be written.\nIf set to \"stdout\" then the debug will go there. Also, you can specify a filehandle that already\nexists by using debugfh.\n\ndebuglevel determines the amount of debug to generate. 0 is the least, 1 is a little more, N is\nthe limit you want.\n\ndebugtime determines wether a timestamp should be preappended to the entry. style defines the\nway the data structure is returned. The two available styles are:\n\ntree - L Tree format\nnode - L format\n\nFor more information see the respective man pages.\n", "subsections": [ { "name": "Listen", "content": "Starts the stream by listening on a port for someone to connect, and send the opening stream\ntag, and then sending a response based on if the received header was correct for this stream.\nServer name, port, and namespace are required otherwise we don't know where to listen and what\nnamespace to accept.\n" }, { "name": "ConnectionAccept", "content": "Accept an incoming connection.\n" }, { "name": "Respond", "content": "If this is a listening socket then we need to respond to the opening .\n" }, { "name": "Connect", "content": "Starts the stream by connecting to the server, sending the opening stream tag, and then waiting\nfor a response and verifying that it is correct for this stream. Server name, port, and\nnamespace are required otherwise we don't know where to send the stream to...\n\nConnect(hostname=>string,\nport=>integer,\nto=>string,\nfrom=>string,\nmyhostname=>string,\nnamespace=>string,\nnamespaces=>array,\nconnectiontype=>string,\nssl=>0|1,\nsslverify =>0x00|0x01|0x02|0x04,\nsslcapath=>string,\nsrv=>string)\n\nOpens a tcp connection to the specified server and sends the proper opening XML Stream tag.\n\"hostname\", \"port\", and \"namespace\" are required. namespaces allows you to use\nXML::Stream::Namespace objects.\n\n\"to\" is needed if you want the stream to attribute to be something other than the hostname you\nare connecting to.\n\n\"from\" is needed if you want the stream from attribute to be something other than the hostname\nyou are connecting from.\n\n\"myhostname\" should not be needed but if the module cannot determine your hostname properly\n(check the debug log), set this to the correct value, or if you want the other side of the\nstream to think that you are someone else. The type determines the kind of connection that is\nmade:\n\n\"tcpip\" - TCP/IP (default)\n\"stdinout\" - STDIN/STDOUT\n\"http\" - HTTP\n\nHTTP recognizes proxies if the ENV variables httpproxy or httpsproxy are set.\n\n\"ssl\" specifies whether an SSL socket should be used for encrypted co- mmunications.\n\n\"sslverify\" determines whether peer certificate verification takes place. See the documentation\nfor the SSLverifymode parameter to IO::Socket::SSL-new()|IO::Socket::SSL>. The default value\nis 0x01 causing the server certificate to be verified, and requiring that sslcapath be set.\n\n\"sslcapath\" should be set to the path to either a directory containing hashed CA certificates,\nor a single file containing acceptable CA certifictes concatenated together. This parameter is\nrequired if sslverify is set to anything other than 0x00 (no verification).\n\nIf srv is specified AND Net::DNS is installed and can be loaded, then an SRV query is sent to\nsrv.hostname and the results processed to replace the hostname and port. If the lookup fails, or\nNet::DNS cannot be loaded, then hostname and port are left alone as the defaults.\n\nThis function returns the same hash from GetRoot() below. Make sure you get the SID (Session ID)\nsince you have to use it to call most other functions in here.\n" }, { "name": "OpenStream", "content": "Send the opening stream and save the root element info.\n" }, { "name": "OpenFile", "content": "Starts the stream by opening a file and setting it up so that Process reads from the filehandle\nto get the incoming stream.\n\nOpenFile(string)\n\nOpens a filehandle to the argument specified, and pretends that it is a stream. It will ignore\nthe outer tag, and not check if it was a . This is useful for writing a program\nthat has to parse any XML file that is basically made up of small packets (like RDF).\n" }, { "name": "Disconnect", "content": "Sends the closing XML tag and shuts down the socket.\n\nDisconnect(sid)\n\nSends the proper closing XML tag and closes the specified socket down.\n" }, { "name": "InitConnection", "content": "Initialize the connection data structure\n" }, { "name": "ParseStream", "content": "Takes the incoming stream and makes sure that only full XML tags gets passed to the parser. If a\nfull tag has not read yet, then the Stream saves the incomplete part and sends the rest to the\nparser.\n" }, { "name": "Process", "content": "Checks for data on the socket and returns a status code depending on if there was data or not.\nIf a timeout is not defined in the call then the timeout defined in Connect() is used. If a\ntimeout of 0 is used then the call blocks until it gets some data, otherwise it returns after\nthe timeout period.\n\nProcess(integer)\n\nWaits for data to be available on the socket. If a timeout is specified then the Process\nfunction waits that period of time before returning nothing. If a timeout period is not\nspecified then the function blocks until data is received. The function returns a hash with\nsession ids as the key, and status values or data as the hash values.\n" }, { "name": "Read", "content": "Takes the data from the server and returns a string\n" }, { "name": "Send", "content": "Takes the data string and sends it to the server\n\nSend(sid, string);\n\nSends the string over the specified connection as is. This does no checking if valid XML was\nsent or not. Best behavior when sending information.\n" }, { "name": "ProcessStreamFeatures", "content": "Process the block.\n" }, { "name": "GetStreamFeature", "content": "Return the value of the stream feature (if any).\n" }, { "name": "ReceivedStreamFeatures", "content": "Have we received the stream:features yet?\n" }, { "name": "ProcessTLSPacket", "content": "Process a TLS based packet.\n" }, { "name": "StartTLS", "content": "Client function to have the socket start TLS.\n\nTLSStartTLS\nSend a in the TLS namespace.\n\nTLSClientProceed\nHandle a packet.\n\nTLSClientSecure\nReturn 1 if the socket is secure, 0 otherwise.\n\nTLSClientDone\nReturn 1 if the TLS process is done\n\nTLSClientError\nreturn the TLS error if any\n\nTLSClientFailure\nHandle a \n\nTLSFailure\nSend a in the TLS namespace\n" }, { "name": "ProcessSASLPacket", "content": "Process a SASL based packet.\n\nSASLAnswerChallenge\nWhen we get a we need to do the grunt work to return a .\n\nSASLAuth\nSend an in the SASL namespace\n\nSASLChallenge\nSend a in the SASL namespace\n\nSASLClient\nThis is a helper function to perform all of the required steps for doing SASL with the server.\n\nSASLClientAuthed\nReturn 1 if we authed via SASL, 0 otherwise\n\nSASLClientDone\nReturn 1 if the SASL process is finished\n\nSASLClientError\nReturn the error if any\n\nSASLClientFailure\nHandle a received \n\nSASLClientSuccess\nhandle a received \n\nSASLFailure\nSend a tag in the SASL namespace\n\nSASLResponse\nSend a tag in the SASL namespace\n" }, { "name": "GetErrorCode", "content": "if you are returned an undef, you can call this function and hopefully learn more information\nabout the problem.\n\nGetErrorCode(sid)\n\nreturns a string for the specified session that will hopefully contain some useful information\nabout why Process or Connect returned an undef to you.\n" }, { "name": "StreamError", "content": "Given a type and text, generate a packet to send back to the other side.\n" }, { "name": "SetXMLData", "content": "Takes a host of arguments and sets a portion of the specified data strucure with that data. The\nfunction works in two modes \"single\" or \"multiple\". \"single\" denotes that the function should\nlocate the current tag that matches this data and overwrite it's contents with data passed in.\n\"multiple\" denotes that a new tag should be created even if others exist.\n\ntype - single or multiple XMLTree - pointer to XML::Stream data object (tree or node) tag - name\nof tag to create/modify (if blank assumes working with top level tag) data - CDATA to set for\ntag attribs - attributes to ADD to tag\n" }, { "name": "GetXMLData", "content": "Takes a host of arguments and returns various data structures that match them.\n\ntype \"existence\" - returns 1 or 0 if the tag exists in the top level.\n\n\"value\" - returns either the CDATA of the tag, or the value of the attribute depending on which\nis sought. This ignores any mark ups to the data and just returns the raw CDATA.\n\n\"value array\" returns an array of strings representing all of the CDATA in the specified tag.\nThis ignores any mark ups to the data and just returns the raw CDATA.\n\n\"tree\" - returns a data structure that represents the XML with the specified tag as the root\ntag. Depends on the format that you are working with.\n\n\"tree array\" returns an array of data structures each with the specified tag as the root tag.\n\n\"child array\" - returns a list of all children nodes not including CDATA nodes.\n\n\"attribs\" - returns a hash with the attributes, and their values, for the things that match the\nparameters\n\n\"count\" - returns the number of things that match the arguments\n\n\"tag\" - returns the root tag of this tree\n\nXMLTree - pointer to XML::Stream data structure\n\n\"tag\" - tag to pull data from. If blank then the top level tag is accessed. \"attrib\" - attribute\nvalue to retrieve. Ignored for types \"value array\", \"tree\", \"tree array\". If paired with value\ncan be used to filter tags based on attributes and values. \"value\" - only valid if an attribute\nis supplied. Used to filter for tags that only contain this attribute. Useful to search through\nmultiple tags that all reference different name spaces.\n\nXPath\nRun an xpath query on a node and return back the result.\n\nXPath(node,path) returns an array of results that match the xpath. node can be any of the three\ntypes (Tree, Node).\n\nXPathCheck\nRun an xpath query on a node and return 1 or 0 if the path is valid.\n\nXML2Config\nTakes an XML data tree and turns it into a hash of hashes. This only works for certain kinds of\nXML trees like this:\n\n\n1\n\nfoo\n\n5\n6\n\n\nThe resulting hash would be:\n\n$hash{bar} = 1;\n$hash{x}->{y} = \"foo\";\n$hash{z}->[0] = 5;\n$hash{z}->[1] = 6;\n\nGood for config files.\n" }, { "name": "Config2XML", "content": "Takes a hash and produces an XML string from it. If the hash looks like this:\n\n$hash{bar} = 1;\n$hash{x}->{y} = \"foo\";\n$hash{z}->[0] = 5;\n$hash{z}->[1] = 6;\n\nThe resulting xml would be:\n\n\n1\n\nfoo\n\n5\n6\n\n\nGood for config files.\n" }, { "name": "EscapeXML", "content": "Simple function to make sure that no bad characters make it into in the XML string that might\ncause the string to be misinterpreted.\n" }, { "name": "UnescapeXML", "content": "Simple function to take an escaped string and return it to normal.\n" }, { "name": "BuildXML", "content": "Takes one of the data formats that XML::Stream supports and call the proper BuildXMLxxx\nfunction on it.\n" }, { "name": "ConstXMLNS", "content": "Return the namespace from the constant string.\n" }, { "name": "GetRoot", "content": "Returns the hash of attributes for the root tag so that any attributes returned\ncan be accessed. from and any xmlns:foobar might be important.\n\nGetRoot(sid)\n\nReturns the attributes that the stream:stream tag sent by the other end listed in a hash for the\nspecified session.\n" }, { "name": "GetSock", "content": "returns the Socket so that an outside function can access it if desired.\n\nGetSock(sid)\n\nReturns a pointer to the IO::Socket object for the specified session.\n" }, { "name": "NewSID", "content": "Returns a session ID to send to an incoming stream in the return header. By default it just\nincrements a counter and returns that, or you can define a function and set it using the\nSetCallBacks function.\n" }, { "name": "SetCallBacks", "content": "Takes a hash with top level tags to look for as the keys and pointers to functions as the\nvalues.\n\nSetCallBacks(node=>function, update=>function);\n\nSets the callback that should be called in various situations.\n\n\"node\" is used to handle the data structures that are built for each top level tag. \"update\" is\nused for when Process is blocking waiting for data, but you want your original code to be\nupdated.\n" } ] }, "VARIABLES": { "content": "$NONBLOCKING\n\nTells the Parser to enter into a nonblocking state. This might cause some funky behavior since\nyou can get nested callbacks while things are waiting. 1=on, 0=off(default).\n", "subsections": [] }, "EXAMPLES": { "content": "simple example\n\nuse XML::Stream qw( Tree );\n\n$stream = XML::Stream->new;\n\nmy $status = $stream->Connect(hostname => \"jabber.org\",\nport => 5222,\nnamespace => \"jabber:client\");\n\nif (!defined($status)) {\nprint \"ERROR: Could not connect to server\\n\";\nprint \" (\",$stream->GetErrorCode(),\")\\n\";\nexit(0);\n}\n\nwhile($node = $stream->Process()) {\n# do something with $node\n}\n\n$stream->Disconnect();\n\nExample using a handler\n\nuse XML::Stream qw( Tree );\n\n$stream = XML::Stream->new;\n$stream->SetCallBacks(node=>\\&noder);\n$stream->Connect(hostname => \"jabber.org\",\nport => 5222,\nnamespace => \"jabber:client\",\ntimeout => undef) || die $!;\n\n# Blocks here forever, noder is called for incoming\n# packets when they arrive.\nwhile(defined($stream->Process())) { }\n\nprint \"ERROR: Stream died (\",$stream->GetErrorCode(),\")\\n\";\n\nsub noder\n{\nmy $sid = shift;\nmy $node = shift;\n# do something with $node\n}\n", "subsections": [] }, "AUTHOR": { "content": "Tweaked, tuned, and brightness changes by Ryan Eatmon, reatmon@ti.com in May of 2000. Colorized,\nand Dolby Surround sound added by Thomas Charron, tcharron@jabber.org By Jeremie in October of\n1999 for http://etherx.jabber.org/streams/\n\nCurrently maintained by Darian Anthony Patrick.\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright (C) 1998-2004 Jabber Software Foundation http://jabber.org/\n\nThis module licensed under the LGPL, version 2.1.\n", "subsections": [] } } } }