[All Packages]  [Previous Package]

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.

Note this SAX functionality is identical to the C version.


SAX callback structure

typedef struct
{
   sword (*startDocument)(void *ctx);
   sword (*endDocument)(void *ctx);
   sword (*startElement)(void *ctx, const oratext *name, struct xmlarray *attrs);
   sword (*endElement)(void *ctx, const oratext *name);
   sword (*characters)(void *ctx, const oratext *ch, size_t len);
   sword (*ignorableWhitespace)(void *ctx, const oratext *ch, size_t len);
   sword (*processingInstruction)(void *ctx, const oratext *target, const oratext *data);
   sword (*notationDecl)(void *ctx, const oratext *name,
                         const oratext *publicId, const oratext *systemId);
   sword (*unparsedEntityDecl)(void *ctx, const oratext *name, const oratext *publicId,
                               const oratext *systemId, const oratext *notationName);
   sword (*nsStartElement)(void *ctx, const oratext *qname,
                           const oratext *local, const oratext *namespace);
} xmlsaxcb;

startDocument

Function:

Called once when document processing is first starting

Prototype:

sword startDocument(void *ctx)

Arguments:

ctx -- User-defined context as passed to initialize()

Returns:

sword -- Error code, 0 for success, non-0 for error.

endDocument

Function:

Called once when document processing is finished

Prototype:

sword endDocument(void *ctx)

Arguments:

ctx -- User-defined context as passed to initialize()

Returns:

sword -- Error code, 0 for success, non-0 for error.

startElement

Function:

Called once for each new document element

Prototype:

sword startElement(void *ctx, const oratext *name, struct xmlarray *attrs)

Arguments:

ctx -- User-defined context as passed to initialize()
name -- name of node
attrs -- array of node's attributes

Returns:

sword -- Error code, 0 for success, non-0 for error.

endElement

Function:

Called once when each document element closes

Prototype:

sword endElement(void *ctx, const oratext *name)

Arguments:

ctx -- User-defined context as passed to initialize()
name -- name of node

Returns:

sword -- Error code, 0 for success, non-0 for error.

characters

Function:

Called for each piece of literal text

Prototype:

sword characters(void *ctx, const oratext *ch, size_t len)

Arguments:

ctx -- User-defined context as passed to initialize()
ch -- pointer to text
len -- number of character in text

Returns:

sword -- Error code, 0 for success, non-0 for error.

IgnorableWhitespace

Function:

Called for each piece of ignorable (non-significant) whitespace

Prototype:

sword ignorableWhitespace(void *ctx, const oratext *ch, size_t len)

Arguments:

ctx -- User-defined context as passed to initialize()
ch -- pointer to whitespace text
len -- number of characters of whitespace

Returns:

sword -- Error code, 0 for success, non-0 for error.

processingInstruction

Function:

Called once for each PI (Processing Instruction)

Prototype:

sword processingInstruction(void *ctx, const oratext *target,
                            const oratext *data)

Arguments:

ctx -- User-defined context as passed to initialize()
target -- PI target
data -- PI data

Returns:

sword -- Error code, 0 for success, non-0 for error.

notationDecl

Function:

Called once for each NOTATION

Prototype:

sword notationDecl(void *ctx, const oratext *name,
                   const oratext *publicId, const oratext *systemId)

Arguments:

ctx -- User-defined context as passed to initialize()
name -- name of notation
publicId -- Public ID
systemId -- System ID

Returns:

sword -- Error code, 0 for success, non-0 for error.

unparsedEntityDecl

Function:

Called once for each unparsed entity declaration

Prototype:

sword unparsedEntityDecl(void *ctx, const oratext *name, const oratext *publicId,
                         const oratext *systemId, const oratext *notationName)

Arguments:

ctx -- User-defined context as passed to initialize()
name -- name of entity
publicId -- Public ID
systemId -- System ID
notationName -- notation name

Returns:

sword -- Error code, 0 for success, non-0 for error.

nsStartElement

Function:

Namespace variant of startElement: Called once for each new document element, when the element uses uses an explicit namespace

Prototype:

sword startElement(void *ctx, const oratext *qname,
                   const oratext *local, const oratext *namespace)

Arguments:

ctx -- User-defined context as passed to initialize()
qname -- qualified namespace
local -- umm
namespace -- yes, well

Returns:

sword -- Error code, 0 for success, non-0 for error.