contenthandler.h

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

//
// ContentHandler.h
//
// $Id: //poco/Main/XML/include/SAX/ContentHandler.h#5 $
//
// SAX2 ContentHandler 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_ContentHandler_INCLUDED
#define SAX_ContentHandler_INCLUDED


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


XML_BEGIN


class Locator;
class Attributes;


class XML_API ContentHandler
	/// Receive notification of the logical content of a document. 
	///
	/// This is the main interface that most SAX applications implement: if the
	/// application needs to be informed of basic parsing events, it implements
	/// this interface and registers an instance with the SAX parser using the setContentHandler
	/// method. The parser uses the instance to report basic document-related events
	/// like the start and end of elements and character data.
	/// 
	/// The order of events in this interface is very important, and mirrors the
	/// order of information in the document itself. For example, all of an element's
	/// content (character data, processing instructions, and/or subelements) will
	/// appear, in order, between the startElement event and the corresponding endElement
	/// event.
	/// 
	/// This interface is similar to the now-deprecated SAX 1.0 DocumentHandler
	/// interface, but it adds support for Namespaces and for reporting skipped
	/// entities (in non-validating XML processors).
	/// Receive notification of the logical content of a document.
{
public:
	virtual void setDocumentLocator(const Locator* loc) = 0;
		/// Receive an object for locating the origin of SAX document events.
		/// 
		/// SAX parsers are strongly encouraged (though not absolutely required) to
		/// supply a locator: if it does so, it must supply the locator to the application
		/// by invoking this method before invoking any of the other methods in the
		/// ContentHandler interface.
		/// 
		/// The locator allows the application to determine the end position of any
		/// document-related event, even if the parser is not reporting an error. Typically,
		/// the application will use this information for reporting its own errors (such
		/// as character content that does not match an application's business rules).
		/// The information returned by the locator is probably not sufficient for use
		/// with a search engine.
		/// 
		/// Note that the locator will return correct information only during the invocation
		/// SAX event callbacks after startDocument returns and before endDocument is
		/// called. The application should not attempt to use it at any other time.

	virtual void startDocument() = 0;
		/// Receive notification of the beginning of a document.
		///
		/// The SAX parser calls this function one time before calling all other 
		/// functions of this class (except SetDocumentLocator).

	virtual void endDocument() = 0;
		/// Receive notification of the end of a document.
		///
		/// The SAX parser will invoke this method only once, and it will be the last
		/// method invoked during the parse. The parser shall not invoke this method
		/// until it has either abandoned parsing (because of an unrecoverable error)
		/// or reached the end of input.

	virtual void startElement(const XMLString& uri, const XMLString& localName, const XMLString& qname, const Attributes& attrList) = 0;
		/// Receive notification of the beginning of an element.
		/// 
		/// The Parser will invoke this method at the beginning of every element in
		/// the XML document; there will be a corresponding endElement event for every
		/// startElement event (even when the element is empty). All of the element's
		/// content will be reported, in order, before the corresponding endElement
		/// event.
		/// 
		/// This event allows up to three name components for each element:
		/// 
		///    1. the Namespace URI;
		///    2. the local name; and
		///    3. the qualified (prefixed) name.
		/// 
		/// Any or all of these may be provided, depending on the values of the http://xml.org/sax/features/namespaces
		/// and the http://xml.org/sax/features/namespace-prefixes properties:
		/// 
		///     * the Namespace URI and local name are required when the namespaces
		/// property is true (the default), and are optional when the namespaces property
		/// is false (if one is specified, both must be);
		///     * the qualified name is required when the namespace-prefixes property
		/// is true, and is optional when the namespace-prefixes property is false (the
		/// default).
		/// 
		/// Note that the attribute list provided will contain only attributes with
		/// explicit values (specified or defaulted): #IMPLIED attributes will be omitted.
		/// The attribute list will contain attributes used for Namespace declarations
		/// (xmlns* attributes) only if the http://xml.org/sax/features/namespace-prefixes
		/// property is true (it is false by default, and support for a true value is
		/// optional).
		/// 
		/// Like characters(), attribute values may have characters that need more than
		/// one char value.

	virtual void endElement(const XMLString& uri, const XMLString& localName, const XMLString& qname) = 0;
		/// Receive notification of the end of an element.
		/// 
		/// The SAX parser will invoke this method at the end of every element in the
		/// XML document; there will be a corresponding startElement event for every
		/// endElement event (even when the element is empty).
		/// 
		/// For information on the names, see startElement.

	virtual void characters(const XMLChar ch[], int start, int length) = 0;
		/// Receive notification of character data.
		/// 
		/// The Parser will call this method to report each chunk of character data.
		/// SAX parsers may return all contiguous character data in a single chunk,
		/// or they may split it into several chunks; however, all of the characters
		/// in any single event must come from the same external entity so that the
		/// Locator provides useful information.
		/// 
		/// The application must not attempt to read from the array outside of the specified
		/// range.
		/// 
		/// Individual characters may consist of more than one Java char value. There
		/// are two important cases where this happens, because characters can't be
		/// represented in just sixteen bits. In one case, characters are represented
		/// in a Surrogate Pair, using two special Unicode values. Such characters are
		/// in the so-called "Astral Planes", with a code point above U+FFFF. A second
		/// case involves composite characters, such as a base character combining with
		/// one or more accent characters.
		/// 
		/// Your code should not assume that algorithms using char-at-a-time idioms
		/// will be working in character units; in some cases they will split characters.
		/// This is relevant wherever XML permits arbitrary characters, such as attribute
		/// values, processing instruction data, and comments as well as in data reported
		/// from this method. It's also generally relevant whenever Java code manipulates
		/// internationalized text; the issue isn't unique to XML.
		/// 
		/// Note that some parsers will report whitespace in element content using the
		/// ignorableWhitespace method rather than this one (validating parsers must
		/// do so).

	virtual void ignorableWhitespace(const XMLChar ch[], int start, int length) = 0;
		/// Receive notification of ignorable whitespace in element content.
		/// 
		/// Validating Parsers must use this method to report each chunk of whitespace
		/// in element content (see the W3C XML 1.0 recommendation, section 2.10): non-validating
		/// parsers may also use this method if they are capable of parsing and using
		/// content models.
		/// 
		/// SAX parsers may return all contiguous whitespace in a single chunk, or they
		/// may split it into several chunks; however, all of the characters in any
		/// single event must come from the same external entity, so that the Locator
		/// provides useful information.
		/// 
		/// The application must not attempt to read from the array outside of the specified
		/// range.

	virtual void processingInstruction(const XMLString& target, const XMLString& data) = 0;
		/// Receive notification of a processing instruction.
		/// 
		/// The Parser will invoke this method once for each processing instruction
		/// found: note that processing instructions may occur before or after the main
		/// document element.
		/// 
		/// A SAX parser must never report an XML declaration (XML 1.0, section 2.8)
		/// or a text declaration (XML 1.0, section 4.3.1) using this method.
		/// 
		/// Like characters(), processing instruction data may have characters that
		/// need more than one char value.

	virtual void startPrefixMapping(const XMLString& prefix, const XMLString& uri) = 0;
		/// Begin the scope of a prefix-URI Namespace mapping.
		/// 
		/// The information from this event is not necessary for normal Namespace processing:
		/// the SAX XML reader will automatically replace prefixes for element and attribute
		/// names when the http://xml.org/sax/features/namespaces feature is true (the
		/// default).
		/// 
		/// There are cases, however, when applications need to use prefixes in character
		/// data or in attribute values, where they cannot safely be expanded automatically;
		/// the start/endPrefixMapping event supplies the information to the application
		/// to expand prefixes in those contexts itself, if necessary.
		/// 
		/// Note that start/endPrefixMapping events are not guaranteed to be properly
		/// nested relative to each other: all startPrefixMapping events will occur
		/// immediately before the corresponding startElement event, and all endPrefixMapping
		/// events will occur immediately after the corresponding endElement event,
		/// but their order is not otherwise guaranteed.
		/// 
		/// There should never be start/endPrefixMapping events for the "xml" prefix,
		/// since it is predeclared and immutable.

	virtual void endPrefixMapping(const XMLString& prefix) = 0;
		/// End the scope of a prefix-URI mapping.
		/// 
		/// See startPrefixMapping for details. These events will always occur immediately
		/// after the corresponding endElement event, but the order of endPrefixMapping
		/// events is not otherwise guaranteed.

	virtual void skippedEntity(const XMLString& name) = 0;
		/// Receive notification of a skipped entity. This is not called for entity
		/// references within markup constructs such as element start tags or markup
		/// declarations. (The XML recommendation requires reporting skipped external
		/// entities. SAX also reports internal entity expansion/non-expansion, except
		/// within markup constructs.)
		/// 
		/// The Parser will invoke this method each time the entity is skipped. Non-validating
		/// processors may skip entities if they have not seen the declarations (because,
		/// for example, the entity was declared in an external DTD subset). All processors
		/// may skip external entities, depending on the values of the http://xml.org/sax/features/external-general-entities
		/// and the http://xml.org/sax/features/external-parameter-entities properties.

protected:
	virtual ~ContentHandler();
};


XML_END


#endif // SAX_ContentHandler_INCLUDED