// // ContentHandler.h // // 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