XDK for C++: Specifications and Cheat Sheet, 7 of 8

XML Parser for C++: SAX API

The SAX API is based on callbacks. Instead of the entire document being parsed and turned into a data structure which may be referenced (by the DOM interface), the SAX interface is serial. As the document is processed, appropriate SAX user callback functions are invoked. Each callback function returns an error code, zero meaning success, any non-zero value meaning failure. If a non-zero code is returned, document processing is stopped.

To use SAX, an xmlsaxcb structure is initialized with function pointers and passed to the xmlinit() call. A pointer to a user-defined context structure may also be included; that context pointer will be passed to each SAX function.

This SAX functionality is identical to the XML Parser for C version.

Table E-5 lists the XML Parser for C++, SAX API functions.

Table E-5 XML Parser for C++: SAX API Functions

SAX Function	Brief Description
characters(void ctx, const oratext ch, size_t len)	Receive notification of character data inside an element.
endDocument(void *ctx)	Receive notification of the end of the document.
endElement(void ctx, const oratext name)	Receive notification of the end of an element.
ignorableWhitespace(void ctx, const oratext ch, size_t len)	Receive notification of ignorable whitespace in element content.
notationDecl(void ctx, const oratext name, const oratext publicId, const oratext systemId)	Receive notification of a notation declaration.
processingInstruction(void ctx, const oratext target, const oratext *data)	Receive notification of a processing instruction.
startDocument(void *ctx)	Receive notification of the beginning of the document.
startElement(void ctx, const oratext name, const struct xmlattrs *attrs)	Receive notification of the start of an element.
unparsedEntityDecl(void ctx, const oratext name, const oratext publicId, const oratext systemId, const oratext *notationName)	Receive notification of an unparsed entity declaration.

Non-SAX Callback Functions
nsStartElement(void ctx, const oratext qname, const oratext local, const oratext namespace, const struct xmlattrs *attrs)	Receive notification of the start of a namespace for an element.