# sax.h

This HTML document was auto-generated from sax.h

## Interface: AttributeList

>     /*****************************************************************
>     Interface: AttributeList
>     Desc:
>     From the Java interface (with modifications):
>     Interface for an element's attribute specifications.
>     The SAX parser implements this interface and passes an instance
>     to the SAX application as the second argument of each startElement
>     event.
>     The instance provided will return valid results only during the
>     scope of the startElement invocation (to save it for future
>     use, the application must make a copy: the AttributeListImpl
>     helper class provides a convenient constructor for doing so).
>     An AttributeList includes only attributes that have been
>     specified or defaulted: #IMPLIED attributes will not be included.
>     There are two ways for the SAX application to obtain information
>     from the AttributeList.  First, it can iterate through the entire
>     list:

>     SAXException * startElement (const unicode * name, AttributeList * atts) {
>     for (int i = 0; i < atts->getLength(); i++) {
>     const unicode * name = atts->getName(i);
>     const unicode * type = atts->getType(i);
>     const unicode * value = atts->getValue(i);
>     [...]
>     }
>     }

>     *
>     (Note that the result of getLength() will be zero if there
>     are no attributes.)
>     *
>     As an alternative, the application can request the value or
>     type of specific attributes:
>     *

>     SAXException * startElement (const unicode * name, AttributeList * atts) {
>     const unicode * identifier = atts->getValue(L"id");
>     const unicode * label = atts->getValue(L"label");
>     [...]
>     }

>     Notes:
>     DirXML provides an implementation of AttributeList via the
>     C++ class AttributeListImpl. There are also C methods to
>     allocated and use an AttributeListImpl.
>     *****************************************************************/

> ### Method: AttributeList::getLength

>     //=========================================================================
>     // Method:	getLength
>     // Desc:	Return the number of attributes in the list. This may be zero.
>     //
>     // Notes:
>     //=========================================================================

>     C++ Signature

>     int
>     AttributeList::getLength(
>     );

> ### Method: AttributeList::getName

>     //=========================================================================
>     // Method:	getName
>     // Desc:	Return the name of an attribute in this list by position. This
>     //			will return null if the specified index is out of range.
>     //
>     // Notes:
>     //=========================================================================

>     C++ Signature

>     const unicode *
>     AttributeList::getName(
>     	int i                                           //0-based index of the attribute
>     );

> ### Method: AttributeList::getType

>     //=========================================================================
>     // Method:	getType
>     // Desc:	Return the type of an attribute in this list by	position. This
>     //			will return null if the specified index is out of range.
>     //
>     // Notes:	The attribute type is one of the strings "CDATA", "ID", "IDREF",
>     //			"IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES" or "NOTATION"
>     //			(always in upper case).
>     //=========================================================================

>     C++ Signature

>     const unicode *
>     AttributeList::getType(
>     	int i                                           //0-based index of the attribute
>     );

> ### Method: AttributeList::getValue

>     //=========================================================================
>     // Method:	getValue
>     // Desc:	Return the value of an attribute in this list by position. This
>     //			will return null if the specified index is out of range.
>     //
>     // Notes:	If the attribute value is a list of tokens (IDREFS, ENTITIES, or
>     //			NMTOKENS), the tokens will be concatenated into a single string
>     //			separated by whitespace.
>     //=========================================================================

>     C++ Signature

>     const unicode *
>     AttributeList::getValue(
>     	int i                                           //0-based index of the attribute
>     );

> ### Method: AttributeList::getType

>     //=========================================================================
>     // Method:	getType
>     // Desc:	Return the type of an attribute in list list by name. If the
>     //			passed name doesn't match an attribute in the list null is
>     //			returned.
>     //
>     // Notes:	The attribute type is one of the strings "CDATA", "ID", "IDREF",
>     //			"IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES" or "NOTATION"
>     //			(always in upper case).
>     //=========================================================================

>     C++ Signature

>     const unicode *
>     AttributeList::getType(
>     	const unicode * name                            //name of attribute
>     );

> ### Method: AttributeList::getValue

>     //=========================================================================
>     // Method:	getValue
>     // Desc:	Return the value of an attribute in list list by name. If the
>     //			passed name doesn't match an attribute in the list null is
>     //			returned.
>     //
>     // Notes:	If the attribute value is a list of tokens (IDREFS, ENTITIES, or
>     //			NMTOKENS), the tokens will be concatenated into a single string
>     //			separated by whitespace.
>     //=========================================================================

>     C++ Signature

>     const unicode *
>     AttributeList::getValue(
>     	const unicode * name                            //name of attribute
>     );

> ### Method: AttributeList::getTypeN

>     //=========================================================================
>     // Method:	getTypeN
>     // Desc:	Return the type of an attribute in list list by name. If the
>     //			passed name doesn't match an attribute in the list null is
>     //			returned.
>     //
>     // Notes:	The attribute type is one of the strings "CDATA", "ID", "IDREF",
>     //			"IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES" or "NOTATION"
>     //			(always in upper case).
>     //
>     //			This method by this name exists only in C.
>     //=========================================================================

>     C++ Signature

>     const unicode *
>     AttributeList::getTypeN(
>     	const unicode * name                            //name of attribute
>     );

> ### Method: AttributeList::getValueN

>     //=========================================================================
>     // Method:	getValueN
>     // Desc:	Return the value of an attribute in list list by name. If the
>     //			passed name doesn't match an attribute in the list null is
>     //			returned.
>     //
>     // Notes:	If the attribute value is a list of tokens (IDREFS, ENTITIES, or
>     //			NMTOKENS), the tokens will be concatenated into a single string
>     //			separated by whitespace.
>     //
>     //			This method by this name exists only in C.
>     //=========================================================================

>     C++ Signature

>     const unicode *
>     AttributeList::getValueN(
>     	const unicode * name                            //name of attribute
>     );

## Interface: DocumentHandler

>     /*****************************************************************
>     Interface: DocumentHandler
>     Desc:
>     From the Java interface:
>     Receive notification of general document events.
>     *
>     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 setDocumentHandler 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.
>     *
>     Application writers who do not want to implement the entire
>     interface can derive a class from HandlerBase, which implements
>     the default functionality; parser writers can instantiate
>     HandlerBase to obtain a default handler.  The application can find
>     the location of any document event using the Locator interface
>     supplied by the Parser through the setDocumentLocator method.
>     Notes:
>     The specification extends the Java org.xml.sax.DocumentHandler
>     with the following methods:
>     SAXException * comment(const unicode * data);
>     int enableExceptions(int enable);
>     *****************************************************************/

> ### Method: DocumentHandler::setDocumentLocator

>     //=========================================================================
>     // Method:	setDocumentLocator
>     // Desc:	Receive an object for locating the origin of SAX document
>     //			events.
>     //
>     // Notes:	From the Java implementation:
>     //			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 DocumentHandler
>     //			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 of the events in this interface.  The
>     //			application should not attempt to use it at any other time.
>     //=========================================================================

>     C++ Signature

>     void
>     DocumentHandler::setDocumentLocator(
>     	Locator * locator
>     );

> ### Method: DocumentHandler::startDocument

>     //=========================================================================
>     // Method:	startDocument
>     // Desc:	Receive notification of the beginning of a document.
>     //
>     // Notes:	From the Java implementation:
>     //			The SAX parser will invoke this method only once, before any
>     //			other methods in this interface or in DTDHandler (except for
>     //			setDocumentLocator).
>     //=========================================================================

>     C++ Signature

>     SAXException *
>     DocumentHandler::startDocument(
>     );

> ### Method: DocumentHandler::endDocument

>     //=========================================================================
>     // Method:	endDocument
>     // Desc:	Receive notification of the end of a document.
>     //
>     // Notes:	From the Java implementation:
>     //			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.
>     //=========================================================================

>     C++ Signature

>     SAXException *
>     DocumentHandler::endDocument(
>     );

> ### Method: DocumentHandler::startElement

>     //=========================================================================
>     // Method:	startElement
>     // Desc:	Receive notification of the beginning of an element.
>     //
>     // Notes:	From the Java implementation:
>     //			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.
>     //
>     //			If the element name has a namespace prefix, the prefix will
>     //			still be attached.  Note that the attribute list provided will
>     //			contain only attributes with explicit values (specified or
>     //			defaulted): #IMPLIED attributes will be omitted.
>     //=========================================================================

>     C++ Signature

>     SAXException *
>     DocumentHandler::startElement(
>     	const unicode * name,
>     	AttributeList * atts
>     );

> ### Method: DocumentHandler::endElement

>     //=========================================================================
>     // Method:	endElement
>     // Desc:	Receive notification of the end of an element.
>     //
>     // Notes:	From the Java implementation:
>     //			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).
>     //
>     //			If the element name has a namespace prefix, the prefix will
>     //			still be attached to the name.
>     //=========================================================================

>     C++ Signature

>     SAXException *
>     DocumentHandler::endElement(
>     	const unicode * name
>     );

> ### Method: DocumentHandler::characters

>     //=========================================================================
>     // Method:	characters
>     // Desc:	Receive notification of character data.
>     //
>     // Notes:	From the Java implementation:
>     //			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.
>     //
>     //			Note that some parsers will report whitespace using the
>     //			ignorableWhitespace() method rather than this one (validating
>     //			parsers must do so).
>     //=========================================================================

>     C++ Signature

>     SAXException *
>     DocumentHandler::characters(
>     	const unicode ch[],
>     	int start,
>     	int length
>     );

> ### Method: DocumentHandler::ignorableWhitespace

>     //=========================================================================
>     // Method:	ignorableWhitespace
>     // Desc:	Receive notification of ignorable whitespace in element content.
>     //
>     // Notes:	From the Java implementation:
>     //			Validating Parsers must use this method to report each chunk
>     //			of ignorable whitespace (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.
>     //=========================================================================

>     C++ Signature

>     SAXException *
>     DocumentHandler::ignorableWhitespace(
>     	const unicode ch[],
>     	int start,
>     	int length
>     );

> ### Method: DocumentHandler::processingInstruction

>     //=========================================================================
>     // Method:	processingInstruction
>     // Desc:	Receive notification of a processing instruction.
>     //
>     // Notes:	From the Java implementation:
>     //			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 should 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.
>     //=========================================================================

>     C++ Signature

>     SAXException *
>     DocumentHandler::processingInstruction(
>     	const unicode * target,
>     	const unicode * data
>     );

> ### Method: DocumentHandler::comment

>     //=========================================================================
>     // Method:	comment
>     // Desc:	Receive notification of a comment.
>     //
>     // Notes:	The parser will invoke this methos once for each comment found.
>     //			This method doesn not exist in the Java interface.
>     //=========================================================================

>     C++ Signature

>     SAXException *
>     DocumentHandler::comment(
>     	const unicode * data
>     );

> ### Method: DocumentHandler::enableExceptions

>     //=========================================================================
>     // Method:	enableExceptions
>     // Desc:	Enable the throwing of C++ exceptions for all methods in this
>     //			interface.
>     //
>     // Notes:	C++ extension
>     //			A C implementation will not support this and will
>     //			always return 0, indicating exceptions are not supported.
>     //=========================================================================

>     C++ Signature

>     int
>     DocumentHandler::enableExceptions(
>     	int enable
>     );

## Interface: DTDHandler

>     /*****************************************************************
>     Interface: DTDHandler
>     Desc:
>     From the Java interface:
>     Receive notification of basic DTD-related events.
>     If a SAX application needs information about notations and
>     unparsed entities, then the application implements this
>     interface and registers an instance with the SAX parser using
>     the parser's setDTDHandler method.  The parser uses the
>     instance to report notation and unparsed entity declarations to
>     the application.
>     The SAX parser may report these events in any order, regardless
>     of the order in which the notations and unparsed entities were
>     declared; however, all DTD events must be reported after the
>     document handler's startDocument event, and before the first
>     startElement event.
>     It is up to the application to store the information for
>     future use (perhaps in a hash table or object tree).
>     If the application encounters attributes of type "NOTATION",
>     "ENTITY", or "ENTITIES", it can use the information that it
>     obtained through this interface to find the entity and/or
>     notation corresponding with the attribute value.
>     Notes:
>     The specification extends the Java org.xml.sax.DTDHandler
>     with the following methods:
>     int enableExceptions(int enable);
>     *****************************************************************/

> ### Method: DTDHandler::notationDecl

>     //=========================================================================
>     // Method:	notationDecl
>     // Desc:	Receive notification of a notation declaration event.
>     //
>     // Notes:	From the Java implementation:
>     //			It is up to the application to record the notation for later
>     //			reference, if necessary.
>     //
>     //			If a system identifier is present, and it is a URL, the SAX
>     //			parser must resolve it fully before passing it to the
>     //			application.
>     //=========================================================================

>     C++ Signature

>     SAXException *
>     DTDHandler::notationDecl(
>     	const unicode * name,
>     	const unicode * publicId,
>     	const unicode * systemId
>     );

> ### Method: DTDHandler::unparsedEntityDecl

>     //=========================================================================
>     // Method:	unparsedEntityDecl
>     // Desc:	Receive notification of an unparsed entity declaration event.
>     //
>     // Notes:	From the Java implementation:
>     //			Note that the notation name corresponds to a notation
>     //			reported by the notationDecl() event.  It is up to the
>     //			application to record the entity for later reference, if
>     //			necessary.
>     //
>     //			If the system identifier is a URL, the parser must resolve it
>     //			fully before passing it to the application.
>     //=========================================================================

>     C++ Signature

>     SAXException *
>     DTDHandler::unparsedEntityDecl(
>     	const unicode * name,
>     	const unicode * publicId,
>     	const unicode * systemId,
>     	const unicode * notationName
>     );

> ### Method: DTDHandler::enableExceptions

>     //=========================================================================
>     // Method:	enableExceptions
>     // Desc:	Enable the throwing of C++ exceptions for all methods in this
>     //			interface.
>     //
>     // Notes:	C++ extension
>     //			A C implementation will not support this and will
>     //			always return 0, indicating exceptions are not supported.
>     //=========================================================================

>     C++ Signature

>     int
>     DTDHandler::enableExceptions(
>     	int enable
>     );

## Interface: EntityResolver

>     /*****************************************************************
>     Interface: EntityResolver
>     Desc:
>     From the Java interface:
>     If a SAX application needs to implement customized handling
>     for external entities, it must implement this interface and
>     register an instance with the SAX parser using the parser's
>     setEntityResolver method.
>     The parser will then allow the application to intercept any
>     external entities (including the external DTD subset and external
>     parameter entities, if any) before including them.
>     Many SAX applications will not need to implement this interface,
>     but it will be especially useful for applications that build
>     XML documents from databases or other specialised input sources,
>     or for applications that use URI types other than URLs.
>     Notes:
>     *****************************************************************/

> ### Method: EntityResolver::resolveEntity

>     //=========================================================================
>     // Method:	resolveEntity
>     // Desc:	Allow the application to resolve external entities.
>     //
>     // Notes:	From the Java implementation:
>     //			The Parser will call this method before opening any external
>     //			entity except the top-level document entity (including the
>     //			external DTD subset, external entities referenced within the
>     //			DTD, and external entities referenced within the document
>     //			element): the application may request that the parser resolve
>     //			the entity itself, that it use an alternative URI, or that it
>     //			use an entirely different input source.
>     //
>     //			Application writers can use this method to redirect external
>     //			system identifiers to secure and/or local URIs, to look up
>     //			public identifiers in a catalogue, or to read an entity from a
>     //			database or other input source (including, for example, a dialog
>     //			box).
>     //
>     //			If the system identifier is a URL, the SAX parser must
>     //			resolve it fully before reporting it to the application.
>     //=========================================================================

>     C++ Signature

>     InputSource *
>     EntityResolver::resolveEntity(
>     	const unicode * publicId,
>     	const unicode * systemId
>     );

## Interface: ErrorHandler

>     /*****************************************************************
>     Interface: ErrorHandler
>     Desc:
>     From the Java interface:
>     Basic interface for SAX error handlers.
>     If a SAX application needs to implement customized error
>     handling, it must implement this interface and then register an
>     instance with the SAX parser using the parser's setErrorHandler
>     method.  The parser will then report all errors and warnings
>     through this interface.
>      The parser shall use this interface instead of throwing an
>     exception: it is up to the application whether to throw an
>     exception for different types of errors and warnings.  Note,
>     however, that there is no requirement that the parser continue to
>     provide useful information after a call to fatalError (in other
>     words, a SAX driver class could catch an exception and report a
>     fatalError).
>     Notes:
>     *****************************************************************/

> ### Method: ErrorHandler::warning

>     //=========================================================================
>     // Method:	warning
>     // Desc:	Receive notification of a warning.
>     //
>     // Notes:	From the Java implementation:
>     //			SAX parsers will use this method to report conditions that
>     //			are not errors or fatal errors as defined by the XML 1.0
>     //			recommendation.  The default behaviour is to take no action.
>     //
>     //			The SAX parser must continue to provide normal parsing events
>     //			after invoking this method: it should still be possible for the
>     //			application to process the document through to the end.
>     //=========================================================================

>     C++ Signature

>     void
>     ErrorHandler::warning(
>     	SAXParseException * exception
>     );

> ### Method: ErrorHandler::error

>     //=========================================================================
>     // Method:	error
>     // Desc:	Receive notification of a recoverable error.
>     //
>     // Notes:	From the Java implementation:
>     //			This corresponds to the definition of "error" in section 1.2
>     //			of the W3C XML 1.0 Recommendation.  For example, a validating
>     //			parser would use this callback to report the violation of a
>     //			validity constraint.  The default behaviour is to take no
>     //			action.
>     //
>     //			The SAX parser must continue to provide normal parsing events
>     //			after invoking this method: it should still be possible for the
>     //			application to process the document through to the end.  If the
>     //			application cannot do so, then the parser should report a fatal
>     //			error even if the XML 1.0 recommendation does not require it to
>     //			do so.
>     //=========================================================================

>     C++ Signature

>     void
>     ErrorHandler::error(
>     	SAXParseException * exception
>     );

> ### Method: ErrorHandler::fatalError

>     //=========================================================================
>     // Method:	fatalError
>     // Desc:	Receive notification of a non-recoverable error.
>     //
>     // Notes:	From the Java implementation:
>     //			This corresponds to the definition of "fatal error" in
>     //			section 1.2 of the W3C XML 1.0 Recommendation.  For example, a
>     //			parser would use this callback to report the violation of a
>     //			well-formedness constraint.
>     //
>     //			The application must assume that the document is unusable
>     //			after the parser has invoked this method, and should continue
>     //			(if at all) only for the sake of collecting addition error
>     //			messages: in fact, SAX parsers are free to stop reporting any
>     //			other events once this method has been invoked.
>     //=========================================================================

>     C++ Signature

>     void
>     ErrorHandler::fatalError(
>     	SAXParseException * exception
>     );

## Interface: Locator

>     /*****************************************************************
>     Interface: Locator
>     Desc:
>     From the Java interface:
>     Interface for associating a SAX event with a document location.
>     If a SAX parser provides location information to the SAX
>     application, it does so by implementing this interface and then
>     passing an instance to the application using the document
>     handler's setDocumentLocator method.  The application can use the
>     object to obtain the location of any other document handler event
>     in the XML source document.
>     Note that the results returned by the object will be valid only
>     during the scope of each document handler method: the application
>     will receive unpredictable results if it attempts to use the
>     locator at any other time.
>     SAX parsers are not required to supply a locator, but they are
>     very strong encouraged to do so.  If the parser supplies a
>     locator, it must do so before reporting any other document events.
>     If no locator has been set by the time the application receives
>     the startDocument event, the application should assume that a
>     locator is not available.
>     Notes:
>     The specification extends the Java org.xml.sax.Locator
>     with the following methods:
>     //destroy is required so that SAXParseException implementations
>     //can destroy the Locator object that they may have
>     void destroy();
>     *****************************************************************/

> ### Method: Locator::getPublicId

>     //=========================================================================
>     // Method:	getPublicId
>     // Desc:	Return the public identifier for the current document event.
>     //			Return is null if no public identifier is available.
>     //
>     // Notes:
>     //=========================================================================

>     C++ Signature

>     const unicode *
>     Locator::getPublicId(
>     );

> ### Method: Locator::getSystemId

>     //=========================================================================
>     // Method:	getSystemId
>     // Desc:	Return the system identifier for the current document event.
>     //			Return is null if no public identifier is available.
>     //
>     // Notes:	From the Java implementation:
>     //			If the system identifier is a URL, the parser must resolve it
>     //			fully before passing it to the application.
>     //=========================================================================

>     C++ Signature

>     const unicode *
>     Locator::getSystemId(
>     );

> ### Method: Locator::getLineNumber

>     //=========================================================================
>     // Method:	getLineNumber
>     // Desc:	Return the line number where the current document event ends.
>     //			Return -1 if none is available.
>     //
>     // Notes:	From the Java implementation:
>     //			Note that this is the line position of the first character
>     //			after the text associated with the document event.
>     //=========================================================================

>     C++ Signature

>     int
>     Locator::getLineNumber(
>     );

> ### Method: Locator::getColumnNumber

>     //=========================================================================
>     // Method:	getColumnNumber
>     // Desc:	Return the column number where the current document event ends.
>     //			Return -1 if none is available.
>     //
>     // Notes:	From the Java implementation:
>     //			Note that this is the column number of the first
>     //			character after the text associated with the document
>     //			event.  The first column in a line is position 1.
>     //=========================================================================

>     C++ Signature

>     int
>     Locator::getColumnNumber(
>     );

> ### Method: Locator::destroy

>     //=========================================================================
>     // Method:	destroy
>     // Desc:	Destroy this locator object.
>     //
>     // Notes:	This must not be called by an application. This must only be
>     //			called by an implementation of SAXParseException.
>     //=========================================================================

>     C++ Signature

>     void
>     Locator::destroy(
>     );

## Interface: Parser

>     /*****************************************************************
>     Interface: Parser
>     Desc:
>     From the Java interface:
>     Basic interface for SAX (Simple API for XML) parsers.
>     All SAX parsers must implement this basic interface: it allows
>     applications to register handlers for different types of events
>     and to initiate a parse from a URI, or a character stream.
>     All SAX parsers must also implement a zero-argument constructor
>     (though other constructors are also allowed).
>     SAX parsers are reusable but not re-entrant: the application
>     may reuse a parser object (possibly with a different input source)
>     once the first parse has completed successfully, but it may not
>     invoke the parse() methods recursively within a parse.
>     Notes:
>     The SAX Parser interface is useful for any reporting of XML
>     structure events. For example, converting a DOM tree to a
>     series of SAX events is one use.
>     The specification extends the Java org.xml.sax.DocumentHandler
>     with the following methods:
>     int enableExceptions(int enable);
>     *****************************************************************/

> ### Method: Parser::setLocale

>     //=========================================================================
>     // Method:	setLocale
>     // Desc:	Allow an application to request a locale for errors and warnings.
>     //
>     // Notes:	From the Java implementation:
>     //			SAX parsers are not required to provide localisation for errors
>     //			and warnings; if they cannot support the requested locale,
>     //			however, they must throw a SAX exception.  Applications may
>     //			not request a locale change in the middle of a parse.
>     //=========================================================================

>     C++ Signature

>     SAXException *
>     Parser::setLocale(
>     	const unicode * locale                          //A standard locale string
>     );

> ### Method: Parser::setEntityResolver

>     //=========================================================================
>     // Method:	setEntityResolver
>     // Desc:	Allow an application to register a custom entity resolver.
>     //
>     // Notes:	From the Java implementation:
>     //			If the application does not register an entity resolver, the
>     //			SAX parser will resolve system identifiers and open connections
>     //			to entities itself (this is the default behaviour implemented in
>     //			HandlerBase).
>     //
>     //			Applications may register a new or different entity resolver
>     //			in the middle of a parse, and the SAX parser must begin using
>     //			the new resolver immediately.
>     //=========================================================================

>     C++ Signature

>     void
>     Parser::setEntityResolver(
>     	EntityResolver * resolver                       //The application's EntityResolver
>     );

> ### Method: Parser::setDTDHandler

>     //=========================================================================
>     // Method:	setDTDHandler
>     // Desc:	Allow an application to register a DTD event handler.
>     //
>     // Notes:	From the Java implementation:
>     //			If the application does not register a DTD handler, all DTD
>     //			events reported by the SAX parser will be silently
>     //			ignored (this is the default behaviour implemented by
>     //			HandlerBase).
>     //
>     //			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.
>     //=========================================================================

>     C++ Signature

>     void
>     Parser::setDTDHandler(
>     	DTDHandler * handler                            //The application's DTDHandler
>     );

> ### Method: Parser::setDocumentHandler

>     //=========================================================================
>     // Method:	setDocumentHandler
>     // Desc:	Allow an application to register a document event handler.
>     //
>     // Notes:	From the Java implementation:
>     //			If the application does not register a document handler, all
>     //			document events reported by the SAX parser will be silently
>     //			ignored (this is the default behaviour implemented by
>     //			HandlerBase).
>     //
>     //			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.
>     //=========================================================================

>     C++ Signature

>     void
>     Parser::setDocumentHandler(
>     	DocumentHandler * handler                       //The application's DocumentHandler
>     );

> ### Method: Parser::setErrorHandler

>     //=========================================================================
>     // Method:	setErrorHandler
>     // Desc:	Allow an application to register an error event handler.
>     //
>     // Notes:	From the Java implementation:
>     //			If the application does not register an error event handler,
>     //			all error events reported by the SAX parser will be silently
>     //			ignored, except for fatalError, which will throw a SAXException
>     //			(this is the default behaviour implemented by HandlerBase).
>     //
>     //			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.
>     //=========================================================================

>     C++ Signature

>     void
>     Parser::setErrorHandler(
>     	ErrorHandler * handler
>     );

> ### Method: Parser::parse

>     //=========================================================================
>     // Method:	parse
>     // Desc:	Parse an XML document.
>     //
>     // Notes:	From the Java implementation:
>     //			The application can use this method to instruct the SAX parser
>     //			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 Parser instead for each
>     //			additional XML document).  Once a parse is complete, an
>     //			application may reuse the same Parser object, possibly with a
>     //			different input source.
>     //
>     //			Note that other objects than "parsers" may implement this
>     //			interface. For example, to convert a DOM tree to SAX events
>     //			a converter might implement this interface and ignore the
>     //			InputSource argument.
>     //=========================================================================

>     C++ Signature

>     SAXException *
>     Parser::parse(
>     	InputSource * inputSource                       //The input source for the top level of the XML document
>     );

> ### Method: Parser::enableExceptions

>     //=========================================================================
>     // Method:	enableExceptions
>     // Desc:	Enable the throwing of C++ exceptions for all methods in this
>     //			interface.
>     //
>     // Notes:	C++ extension
>     //			A C implementation will not support this and will
>     //			always return 0, indicating exceptions are not supported.
>     //=========================================================================

>     C++ Signature

>     int
>     Parser::enableExceptions(
>     	int enable
>     );

## Interface: InputSource

>     /*****************************************************************
>     Interface: InputSource
>     Desc:
>     From the Java interface:
>     A single input source for an XML entity.
>     This class allows a SAX application to encapsulate information
>     about an input source in a single object, which may include
>     a public identifier, a system identifier, a byte stream (possibly
>     with a specified encoding), and/or a character stream.
>     There are two places that the application will deliver this
>     input source to the parser: as the argument to the Parser.parse
>     method, or as the return value of the EntityResolver.resolveEntity
>     method.
>     An InputSource object belongs to the application: the SAX parser
>     shall never modify it in any way (it may modify a copy if
>     necessary).
>     Notes:
>     This interface diverges from the Java interface because of the
>     lack of a common stream functionality in C/C++.
>     The primary divergence is the method readByteChunk() which the
>     SAX parser can call to read a chunk of the data stream at a
>     time.
>     DirXML provides an implementation via the C++ InputSourceImpl class.
>     *****************************************************************/

> ### Method: InputSource::setPublicIdd

>     //=========================================================================
>     // Method:	setPublicIdd
>     // Desc:	Set the public identifier for this input source.
>     //
>     // Notes:	From the Java implementation:
>     //			The public identifier is always optional: if the application
>     //			writer includes one, it will be provided as part of the
>     //			location information.
>     //=========================================================================

>     C++ Signature

>     void
>     InputSource::setPublicId(
>     	const char * publicId                           //public id string
>     );

> ### Method: InputSource::getPublicId

>     //=========================================================================
>     // Method:	getPublicId
>     // Desc:	Get the public identifier for this input source. Return null
>     //			if no public id was supplied.
>     //
>     // Notes:
>     //=========================================================================

>     C++ Signature

>     const char *
>     InputSource::getPublicId(
>     );

> ### Method: InputSource::getSystemId

>     //=========================================================================
>     // Method:	getSystemId
>     // Desc:	Set the system identifier for this input source.
>     //
>     // Notes:	From the Java implementation:
>     //			The system identifier is optional if there is a byte stream
>     //			or a character stream, but it is still useful to provide one,
>     //			since the application can use it to resolve relative URIs
>     //			and can include it in error messages and warnings (the parser
>     //			will attempt to open a connection to the URI only if
>     //			there is no byte stream or character stream specified).
>     //
>     //			If the application knows the character encoding of the
>     //			object pointed to by the system identifier, it can register
>     //			the encoding using the setEncoding method.
>     //
>     //			If the system ID is a URL, it must be fully resolved.
>     //=========================================================================

>     C++ Signature

>     void
>     InputSource::setSystemId(
>     	const char * systemId                           //system id string
>     );

> ### Method: InputSource::getSystemId

>     //=========================================================================
>     // Method:	getSystemId
>     // Desc:	Get the system identifier for this input source.
>     //
>     // Notes:	From the Java implementation:
>     //			The getEncoding method will return the character encoding
>     //			of the object pointed to, or null if unknown.
>     //
>     //			If the system ID is a URL, it will be fully resolved.
>     //=========================================================================

>     C++ Signature

>     const char *
>     InputSource::getSystemId(
>     );

> ### Method: InputSource::setByteStream

>     //=========================================================================
>     // Method:	setByteStream
>     // Desc:	Set the byte stream for this input source.
>     //
>     // Notes:	From the Java implementation:
>     //			The SAX parser will ignore this if there is also a character
>     //			stream specified, but it will use a byte stream in preference
>     //			to opening a URI connection itself.
>     //
>     //			If the application knows the character encoding of the
>     //			byte stream, it should set it with the setEncoding method.
>     //=========================================================================

>     C++ Signature

>     void
>     InputSource::setByteStream(
>     	const unsigned char * byteStream,               //array of bytes
>     	int length                                      //length of array in bytes
>     );

> ### Method: InputSource::getByteStream

>     //=========================================================================
>     // Method:	getByteStream
>     // Desc:	Get the byte stream for this input source.
>     //
>     // Notes:	From the Java implementation:
>     //			The getEncoding method will return the character
>     //			encoding for this byte stream, or null if unknown.
>     //=========================================================================

>     C++ Signature

>     const unsigned char *
>     InputSource::getByteStream(
>     	int * length                                    //pointer to variable to receive length of array
>     );

> ### Method: InputSource::setEncoding

>     //=========================================================================
>     // Method:	setEncoding
>     // Desc:	Set the character encoding, if known.
>     //
>     // Notes:	From the Java implementation:
>     //			The encoding must be a string acceptable for an
>     //			XML encoding declaration (see section 4.3.3 of the XML 1.0
>     //			recommendation).
>     //
>     //			This method has no effect when the application provides a
>     //			character stream.
>     //=========================================================================

>     C++ Signature

>     void
>     InputSource::setEncoding(
>     	const unicode * encoding                        //encoding string
>     );

> ### Method: InputSource::getEncoding

>     //=========================================================================
>     // Method:	getEncoding
>     // Desc:	Get the character encoding for a byte stream or URI.
>     //
>     // Notes:
>     //=========================================================================

>     C++ Signature

>     const unicode *
>     InputSource::getEncoding(
>     );

> ### Method: InputSource::setCharacterStream

>     //=========================================================================
>     // Method:	setCharacterStream
>     // Desc:	Set the character stream for this input source.
>     //
>     // Notes:	From the Java implementation:
>     //			If there is a character stream specified, the SAX parser
>     //			will ignore any byte stream and will not attempt to open
>     //			a URI connection to the system identifier.
>     //=========================================================================

>     C++ Signature

>     void
>     InputSource::setCharacterStream(
>     	const unicode * charStream,                     //array of characters
>     	int length                                      //length of array in characters
>     );

> ### Method: InputSource::getCharacterStream

>     //=========================================================================
>     // Method:	getCharacterStream
>     // Desc:	Get the character stream for this input source.
>     //
>     // Notes:
>     //=========================================================================

>     C++ Signature

>     const unicode *
>     InputSource::getCharacterStream(
>     	int * length                                    //pointer to variable to receive length of array
>     );

> ### Method: InputSource::readByteChunk

>     //=========================================================================
>     // Method:	readByteChunk
>     // Desc:	Return the number of bytes passed from the input
>     //			source.
>     //
>     // Notes:
>     //			The passed buffer must be at least as large as the count
>     //			parameter.
>     //
>     //			When the return value is less than count, the source is
>     //			exhausted.
>     //=========================================================================

>     C++ Signature

>     int
>     InputSource::readByteChunk(
>     	int count,                                      //number of bytes to read
>     	unsigned char * buffer                          //buffer for returned bytes
>     );

## Interface: SAXException

>     /*****************************************************************
>     Interface: SAXException
>     Desc:
>     From the Java interface:
>     Encapsulate a general SAX error or warning.
>     This class can contain basic error or warning information from
>     either the XML parser or the application: a parser writer or
>     application writer can subclass it to provide additional
>     functionality.  SAX handlers may throw this exception or
>     any exception subclassed from it.
>     If the application needs to pass through other types of
>     exceptions, it must wrap those exceptions in a SAXException
>     or an exception derived from a SAXException.
>     If the parser or application needs to include information about a
>     specific location in an XML document, it should use the
>     SAXParseException subclass.
>     Notes:
>     *****************************************************************/

> ### Method: SAXException::getMessage

>     //=========================================================================
>     // Method:	getMessage
>     // Desc:	Return the text message associated with this exception (if any).
>     //
>     // Notes:
>     //=========================================================================

>     C++ Signature

>     const unicode *
>     SAXException::getMessage(
>     );

> ### Method: SAXException::destroy

>     //=========================================================================
>     // Method:	destroy
>     // Desc:	Destroy this SAXException
>     //
>     // Notes:
>     //=========================================================================

>     C++ Signature

>     void
>     SAXException::destroy(
>     );

## Interface: SAXParseException

>     /*****************************************************************
>     Interface: SAXParseException
>     Desc:
>     From the Java interface:
>     Encapsulate an XML parse error or warning.
>     This exception will include information for locating the error
>     in the original XML document.  Note that although the application
>     will receive a SAXParseException as the argument to the handlers
>     in the ErrorHandler interface, the application is not actually
>     required to throw the exception; instead, it can simply read the
>     information in it and take a different action.
>     Notes:
>     *****************************************************************/

> ### Method: SAXParseException::setLocator

>     //=========================================================================
>     // Method:	setLocator
>     // Desc:	Allow a Parser to set a Locator object with information on
>     //			the exception.
>     //
>     // Notes:
>     //=========================================================================

>     C++ Signature

>     void
>     SAXParseException::setLocator(
>     	Locator * locator                               //Locator object
>     );

> ### Method: SAXParseException::getLocator

>     //=========================================================================
>     // Method:	getLocator
>     // Desc:	Get the Locator (if any) set by the Parser.
>     //
>     // Notes:
>     //=========================================================================

>     C++ Signature

>     Locator *
>     SAXParseException::getLocator(
>     );