############################################################################## # # This library is free software; you can redistribute it and/or # modify it under the terms of the GNU Library General Public # License as published by the Free Software Foundation; either # version 2 of the License, or (at your option) any later version. # # This library is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU # Library General Public License for more details. # # You should have received a copy of the GNU Library General Public # License along with this library; if not, write to the # Free Software Foundation, Inc., 59 Temple Place - Suite 330, # Boston, MA 02111-1307, USA. # # Jabber # Copyright (C) 1998-2004 Jabber Software Foundation http://jabber.org/ # ############################################################################## package XML::Stream; =head1 NAME XML::Stream - Creates an XML Stream connection and parses return data =head1 SYNOPSIS XML::Stream is an attempt at solidifying the use of XML via streaming. =head1 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. =head1 METHODS =cut use 5.008; use strict; use warnings; use Sys::Hostname; use IO::Socket; use IO::Select; use FileHandle; use Carp; use POSIX; use Authen::SASL; use MIME::Base64; use utf8; use Encode; use Scalar::Util qw(weaken); use XML::Stream::IO::Select::Win32; use XML::Stream::Tools; $SIG{PIPE} = "IGNORE"; use vars qw($VERSION $PAC $SSL $NONBLOCKING %HANDLERS $NETDNS %XMLNS ); ############################################################################## # Define the namespaces in an easy/constant manner. #----------------------------------------------------------------------------- # 0.9 #----------------------------------------------------------------------------- $XMLNS{'stream'} = "http://etherx.jabber.org/streams"; #----------------------------------------------------------------------------- # 1.0 #----------------------------------------------------------------------------- $XMLNS{'xmppstreams'} = "urn:ietf:params:xml:ns:xmpp-streams"; $XMLNS{'xmpp-bind'} = "urn:ietf:params:xml:ns:xmpp-bind"; $XMLNS{'xmpp-sasl'} = "urn:ietf:params:xml:ns:xmpp-sasl"; $XMLNS{'xmpp-session'} = "urn:ietf:params:xml:ns:xmpp-session"; $XMLNS{'xmpp-tls'} = "urn:ietf:params:xml:ns:xmpp-tls"; ############################################################################## if (eval "require Net::DNS;" ) { require Net::DNS; import Net::DNS; $NETDNS = 1; } else { $NETDNS = 0; } $VERSION = "1.24"; $NONBLOCKING = 0; #use XML::Stream::Namespace; use XML::Stream::Parser; use XML::Stream::XPath; ############################################################################## # # Setup the exportable objects # ############################################################################## my @EXPORT_OK = qw(Tree Node); sub import { my $class = shift; foreach my $module (@_) { eval "use XML::Stream::$module;"; die($@) if ($@); my $lc = lc($module); eval("\$HANDLERS{\$lc}->{startElement} = \\&XML::Stream::${module}::_handle_element;"); eval("\$HANDLERS{\$lc}->{endElement} = \\&XML::Stream::${module}::_handle_close;"); eval("\$HANDLERS{\$lc}->{characters} = \\&XML::Stream::${module}::_handle_cdata;"); } } =pod =head2 new new( debug => string, debugfh => FileHandle, debuglevel => 0|1|N, debugtime => 0|1, style => string) Creates the XML::Stream object. B 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 B. B determines the amount of debug to generate. 0 is the least, 1 is a little more, N is the limit you want. B determines wether a timestamp should be preappended to the entry. B