mirror of
https://github.com/pocoproject/poco.git
synced 2024-12-21 05:03:36 +01:00
243 lines
11 KiB
C++
Executable File
243 lines
11 KiB
C++
Executable File
//
|
|
// ContentHandler.h
|
|
//
|
|
// $Id: //poco/1.4/XML/include/Poco/SAX/ContentHandler.h#1 $
|
|
//
|
|
// Library: XML
|
|
// Package: SAX
|
|
// Module: SAX
|
|
//
|
|
// SAX2 ContentHandler Interface.
|
|
//
|
|
// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
|
|
// and Contributors.
|
|
//
|
|
// SPDX-License-Identifier: BSL-1.0
|
|
//
|
|
|
|
|
|
#ifndef SAX_ContentHandler_INCLUDED
|
|
#define SAX_ContentHandler_INCLUDED
|
|
|
|
|
|
#include "Poco/XML/XML.h"
|
|
#include "Poco/XML/XMLString.h"
|
|
|
|
|
|
namespace Poco {
|
|
namespace XML {
|
|
|
|
|
|
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 XMLChar value. There
|
|
/// are three 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. And most important, if XMLChar is a plain
|
|
/// char, characters are encoded in UTF-8.
|
|
///
|
|
/// 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 C++ 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();
|
|
};
|
|
|
|
|
|
} } // namespace Poco::XML
|
|
|
|
|
|
#endif // SAX_ContentHandler_INCLUDED
|