xmlreader.h

This software aims to create an applet and panel tools to manage a wireless interface card, such as

//
// XMLReader.h
//
// $Id: //poco/Main/XML/include/SAX/XMLReader.h#5 $
//
// SAX2 XMLReader Interface.
//
// Copyright (c) 2004, Guenter Obiltschnig/Applied Informatics.
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
//
// 1. Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
//
// 3. Redistributions in any form must be accompanied by information on
//    how to obtain complete source code for this software and any
//    accompanying software that uses this software.  The source code
//    must either be included in the distribution or be available for no
//    more than the cost of distribution plus a nominal fee, and must be
//    freely redistributable under reasonable conditions.  For an
//    executable file, complete source code means the source code for all
//    modules it contains.  It does not include source code for modules or
//    files that typically accompany the major components of the operating
//    system on which the executable file runs.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
// FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
// COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
// BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
// ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.
//


#ifndef SAX_XMLReader_INCLUDED
#define SAX_XMLReader_INCLUDED


#ifndef XML_XML_INCLUDED
#include "XML/XML.h"
#endif
#ifndef XML_XMLString_INCLUDED
#include "XML/XMLString.h"
#endif


XML_BEGIN


class EntityResolver;
class DTDHandler;
class ContentHandler;
class ErrorHandler;
class InputSource;
class LexicalHandler;
class NamespaceHandler;


class XML_API XMLReader
	/// Interface for reading an XML document using callbacks. 
	/// XMLReader is the interface that an XML parser's SAX2 driver must 
	/// implement. This interface allows an application to set and
	/// query features and properties in the parser, to register event handlers 
	/// for document processing, and to initiate a document parse.
	/// All SAX interfaces are assumed to be synchronous: the parse methods must not 
	/// return until parsing is complete, and readers
	/// must wait for an event-handler callback to return before reporting the next event.
{
public:
	virtual void setEntityResolver(EntityResolver* pResolver) = 0;
		/// Allow an application to register an entity resolver.
		///
		/// If the application does not register an entity resolver, the 
		/// XMLReader will perform its own default resolution.
		/// 
		/// Applications may register a new or different resolver in the middle of a 
		/// parse, and the SAX parser must begin using the new resolver immediately.

	virtual EntityResolver* getEntityResolver() const = 0;
		/// Return the current entity resolver.

	virtual void setDTDHandler(DTDHandler* pDTDHandler) = 0;
		/// Allow an application to register a DTD event handler.
		///
		/// If the application does not register a DTD handler, all DTD events reported by 
		/// the SAX parser will be silently ignored.
		/// 
		/// Applications may register a new or different handler in the middle of a parse, 
		/// and the SAX parser must begin using the new handler immediately.

	virtual DTDHandler* getDTDHandler() const = 0;
		/// Return the current DTD handler.

	virtual void setContentHandler(ContentHandler* pContentHandler) = 0;
		/// Allow an application to register a content event handler.
		/// 
		/// If the application does not register a content handler, all content events 
		/// reported by the SAX parser will be silently ignored.
		/// 
		/// Applications may register a new or different handler in the middle of a parse, 
		/// and the SAX parser must begin using the new handler immediately.

	virtual ContentHandler* getContentHandler() const = 0;
		/// Return the current content handler.

	virtual void setErrorHandler(ErrorHandler* pErrorHandler) = 0;
		/// Allow an application to register an error event handler.
		///
		/// If the application does not register an error handler, all error events reported by 
		/// the SAX parser will be silently ignored; however, normal processing may not continue. 
		/// It is highly recommended that all SAX applications implement an error handler to avoid 
		/// unexpected bugs.
		/// 
		/// Applications may register a new or different handler in the middle of a parse, and the 
		/// SAX parser must begin using the new handler immediately.

	virtual ErrorHandler* getErrorHandler() const = 0;
		/// Return the current error handler.
	
	virtual void setFeature(const XMLString& featureId, bool state) = 0;
		/// Set the state of a feature.
		///
		/// The feature name is any fully-qualified URI. It is possible for an XMLReader to 
		/// expose a feature value but to be unable to change the current value. Some feature 
		/// values may be immutable or mutable only in specific contexts, such as before, during, 
		/// or after a parse.
		/// 
		/// All XMLReaders are required to support setting http://xml.org/sax/features/namespaces 
		/// to true and http://xml.org/sax/features/namespace-prefixes to false.

	virtual bool getFeature(const XMLString& featureId) const = 0;
		/// Look up the value of a feature.
		///
		/// The feature name is any fully-qualified URI. It is possible for an XMLReader 
		/// to recognize a feature name but temporarily be unable to return its value. 
		/// Some feature values may be available only in specific contexts, such as before, 
		/// during, or after a parse. Also, some feature values may not be programmatically 
		/// accessible. (In the case of an adapter for SAX1 Parser, there is no 
		/// implementation-independent way to expose whether the underlying parser is performing 
		/// validation, expanding external entities, and so forth.)
		/// 
		/// All XMLReaders are required to recognize the 
		/// http://xml.org/sax/features/namespaces and the 
		/// http://xml.org/sax/features/namespace-prefixes feature names.
		/// Implementors are free (and encouraged) to invent their own features, 
		/// using names built on their own URIs.
		
	virtual void setProperty(const XMLString& propertyId, const XMLString& value) = 0;
		/// Set the value of a property.
		/// 
		/// The property name is any fully-qualified URI. It is possible for an XMLReader 
		/// to recognize a property name but to be unable to change the current value. 
		/// Some property values may be immutable or mutable only in specific contexts, 
		/// such as before, during, or after a parse.
		/// 
		/// XMLReaders are not required to recognize setting any specific property names, though a 
		/// core set is defined by SAX2.
		/// 
		/// This method is also the standard mechanism for setting extended handlers.

	virtual void setProperty(const XMLString& propertyId, void* value) = 0;
		/// Set the value of a property.
		/// See also setProperty(const XMLString&, const XMLString&).

	virtual void* getProperty(const XMLString& propertyId) const = 0;
		/// Look up the value of a property.
		/// String values are returned as XMLChar*
		/// The property name is any fully-qualified URI. It is possible for an XMLReader to 
		/// recognize a property name but temporarily be unable to return its value. Some property 
		/// values may be available only in specific contexts, such as before, during, or after a parse.
		///
		/// XMLReaders are not required to recognize any specific property names, though an initial 
		/// core set is documented for SAX2.
		/// 
		/// Implementors are free (and encouraged) to invent their own properties, using names 
		/// built on their own URIs.

	virtual void parse(InputSource* pSource) = 0;
		/// Parse an XML document.
		/// 
		/// The application can use this method to instruct the XML reader to begin parsing an 
		/// XML document from any valid input source (a character stream, a byte stream, or a URI).
		/// 
		/// Applications may not invoke this method while a parse is in progress (they should create 
		/// a new XMLReader instead for each nested XML document). Once a parse is complete, an 
		/// application may reuse the same XMLReader object, possibly with a different input source. 
		/// Configuration of the XMLReader object (such as handler bindings and values established for 
		/// feature flags and properties) is unchanged by completion of a parse, unless the definition of that 
		/// aspect of the configuration explicitly specifies other behavior. (For example, feature flags or 
		/// properties exposing characteristics of the document being parsed.)
		/// 
		/// During the parse, the XMLReader will provide information about the XML document through the registered 
		/// event handlers.
		///
		/// This method is synchronous: it will not return until parsing has ended. If a client application 
		/// wants to terminate parsing early, it should throw an exception.

	virtual void parse(const XMLString& systemId) = 0;
		/// Parse an XML document from a system identifier.
		/// See also parse(InputSource*).

	// SAX Features
	static const XMLString FEATURE_VALIDATION;
	static const XMLString FEATURE_NAMESPACES;
	static const XMLString FEATURE_NAMESPACE_PREFIXES;
	static const XMLString FEATURE_EXTERNAL_GENERAL_ENTITIES;
	static const XMLString FEATURE_EXTERNAL_PARAMETER_ENTITIES;
	static const XMLString FEATURE_STRING_INTERNING;
	
	// SAX Properties
	static const XMLString PROPERTY_DECLARATION_HANDLER;
	static const XMLString PROPERTY_LEXICAL_HANDLER;

protected:
	virtual ~XMLReader();
};


XML_END


#endif // SAX_XMLReader_INCLUDED