[All Packages] [Previous] [Next]
SAX is a standard interface for event-based XML parsing, developed collaboratively by the members of the XML-DEV mailing list.
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.
The 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;
| Name | Declaration | Definition |
|---|---|---|
| ORATEXT* | typedef unsigned char oratext; | Pointer to data (any encoding, including Unicode -- cast as needed) |
| SWORD | typedef signed int sword; | Return value for user SAX callback functions; 0 means success |
| XMLNODES* | typedef struct xmlnodes xmlnodes; | Pointer to list of nodes (attributes of an element). |
Note: xmlnodes is an opaque type and cannot be referenced directly. Instead, use DOM functions getAttributeIndex et al.
| characters | Receive notification of character data inside an element. |
| endDocument | Receive notification of the end of the document. |
| endElement | Receive notification of the end of an element. |
| ignorableWhitespace | Receive notification of ignorable whitespace in element content. |
| notationDecl | Receive notification of a notation declaration. |
| processingInstruction | Receive notification of a processing instruction. |
| startDocument | Receive notification of the beginning of the document. |
| startElement | Receive notification of the start of an element. |
| unparsedEntityDecl | Receive notification of an unparsed entity declaration. |
| attributeDecl | Receive notification about an element attribute declaration in the DTD |
| comment | Receive notification about a comment in the XML document |
| elementDecl | Receive notification about an element declaration in the DTD |
| nsStartElement | Receive notification of the start of a namespace for an element |
| xmlDecl | Receive notification of an XML declaration (XMLDecl) |
sword (*startDocument)(void *ctx);
| ctx | (IN) | client context |
sword (*endDocument)(void *ctx);
| ctx | (IN) | client context |
sword (*startElement)(void *ctx, const oratext *name, const struct xmlnodes *attrs);
| ctx | (IN) | client context |
| name | (IN) | element type name |
| attrs | (IN) | specified or defaulted attributes |
sword (*nsStartElement)(void *ctx, const oratext *qname, const oratext *local,
const oratext *namespace, const struct xmlnodes *attrs);
| ctx | (IN) | client context |
| qname | (IN) | element fully qualified name |
| local | (IN) | element local name |
| namespace | (IN) | element namespace (URI) |
| attrs | (IN) | specified or defaulted attributes |
sword (*endElement)(void *ctx, const oratext *name);
| ctx | (IN) | client context |
| name | (IN) | element type name |
sword (*characters)(void *ctx, const oratext *ch, size_t len);
| ctx | (IN) | client context pointer |
| ch | (IN) | pointer to character data array |
| len | (IN) | number of characters to use from the pointer |
sword (*ignorableWhitespace)(void *ctx, const oratext *ch, size_t len);
| ctx | (IN) | client context |
| ch | (IN) | pointer to whitespace character array |
| len | (IN) | number of characters to use from the pointer |
sword (*processingInstruction)(void *ctx, const oratext *target, const oratext *data);
| ctx | (IN) | client context |
| target | (IN) | processing instruction target |
| data | (IN) | processing instruction data, or NULL if none is supplied |
sword (*comment)(void *ctx, const oratext *data);
| ctx | (IN) | client context |
| data | (IN) | body of comment |
sword (*elementDecl)(void *ctx, const oratext *name, const oratext *content);
| ctx | (IN) | client context |
| name | (IN) | name of element being declared |
| content | (IN) | content model for element |
sword (*attributeDecl)(void *ctx, const oratext *elem,
const oratext *attr, const oratext *body);
| ctx | (IN) | client context |
| name | (IN) | name of element that attribute is being declared for |
| attr | (IN) | name of attribute being declared |
| body | (IN) | body of attribute declaration |
sword (*notationDecl)(void *ctx, const oratext *name, const oratext *publicId,
const oratext *systemId);
| ctx | (IN) | client context |
| name | (IN) | notation name |
| publicIdI | (IN) | notation public identifier, or NULL if not available |
| systemId | (IN) | notation system identifier |
sword (*unparsedEntityDecl)(void *ctx, const oratext *name, const oratext *publicId,
const oratext *systemId, const oratext *notationName);
| ctx | (IN) | client context |
| name | (IN) | entity name |
| publicId | (IN) | entity public identifier, or NULL if not available |
| systemId | (IN) | entity system identifier |
| notationName | (IN) | name of the associated notation |
sword (*xmlDecl)(void *ctx, const oratext *version, boolean encoding);
| ctx | (IN) | client context |
| version | (IN) | version string from declaration (in data encoding) |
| encoding | (IN) | flag indicating if encoding was specified in declaration |