[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, const struct xmlnodes *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 *nsp, const struct xmlnodes *attrs);
   sword (*comment)(void *ctx, const oratext *data);
   sword (*elementDecl)(void *ctx, const oratext *name, const oratext *content);
   sword (*attributeDecl)(void *ctx, const oratext *elem,
                          const oratext *attr, const oratext *body);
   sword (*xmlDecl)(void *ctx, const oratext *version, boolean encoding);

} 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, const struct xmlnodes *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,
                   const struct xmlnodes *attrs)

Arguments:

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

qname -- qualified namespace

local -- element local name

namespace -- element namespace

attrs -- specified or defaulted attributes

Returns:

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

comment

Function:

Receives notification about an XML source comment.

Prototype:

sword comment(void *ctx, const oratext *data)

Arguments:

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

data -- body of comment

Returns:

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

elementDecl

Function:

Receives notification about an element declaration.

Prototype:

sword elementDecl(void *ctx, const oratext *name, const oratext *content)

Arguments:

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

name -- name of element being declared

content -- content model for element

Returns:

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

attributeDecl

Function:

Receives notification about an element's attribute declaration.

Prototype:

sword attributeDecl(void *ctx, const oratext *elem,
                    const oratext *attr, const oratext *body)

Arguments:

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

elem -- name of element that attribute is being declared for

attr -- name of attribute being declared

body -- body of attribute declaration

Returns:

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

xmlDecl

Function:

Receives notification about an XML declaration (XMLDecl).

Prototype:

sword xmlDecl(void *ctx, const oratext *version, boolean encoding)

Arguments:

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

version -- version number specfied in declaration

encoding -- flag indicating if encoding was specified

Returns:

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

Notes:

If an encoding was specified in the XMLDecl, encoding will be TRUE. Since the document's data will be converted to the chosen data encoding, there is no point in providing the original encoding. Instead, the data encoding can get retrieved with getEncoding(). Any new XMLDecl written out will specify the data encoding.