[All Packages]  [Callback]  [DOM]  [Parser]  [SAX]  [XSLT]  [Functions]  [Datatypes]

Package SAX

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.

Interface SAX

attributeDecl Receives SAX notification of an attribute's declaration
cdata Receives SAX notification of CDATA
characters Receives SAX notification of character data
comment Receives SAX notification of a comment
elementDecl Receives SAX notification of an element's declaration
endDocument Receives SAX end-of-document notification
endElement Receives SAX end-of-element notification
ignorableWhitespace Receives SAX notification of ignorable (whitespace) data
notationDecl Receives SAX notification of a notation declaration
nsStartElement Receives SAX namespace-aware start-of-element notification
processingInstruction Receives SAX notification of a processing instruction
startDocument Receives SAX start-of document notification
startElement Receives SAX start-of-element notification
unparsedEntityDecl Receives SAX notification of a unparsed entity declaration
xmlDecl Receives SAX notification of an XML declaration

attributeDecl
Name attributeDecl
Interface SAX; SAX X
Purpose Receives SAX notification of an attribute's declaration
Prototype sword (*attributeDecl)(void *ctx, const oratext *elem,
                       const oratext *attr, const oratext *body);
Arguments
ctx (IN) user's SAX context [see xmlinit]
elem (IN) element that attribute is declared for [in data encoding]
attr (IN) attribute's name [in data encoding]
body (IN) body of attribute declaration [in data encoding]
Returns (sword) error code, XMLERR_OK [0] for success
Description This event marks an element declaration in the DTD. The element's name and content will be in the data encoding. Note that an attribute may be declared before the element it belongs to!

Example <?xml version="1.0"?>
<!DOCTYPE foo [
    <!ATTLIST a id ID #IMPLIED>
]>
...
  -SAX->
xmlDecl(version="1.0", encoding=NULL)
attributeDecl(elem="a", name="id", body="ID #IMPLIED")
...
See Also xmlinit, attributeDecl

cdata
Name cdata
Interface SAX; SAX 1
Purpose Receives SAX notification of CDATA
Prototype sword (*cdata)(void *ctx, const oratext *ch, size_t len);
Arguments
ctx (IN) user's SAX context [see xmlinit]
ch (IN) pointer to CDATA [in data encoding]
len (IN) length of CDATA [in characters]
Returns (sword) error code, XMLERR_OK [0] for success
Description This event marks CDATA, as distinct from Text. If no CDATA callback is provided, the Text callback will be invoked. The data will be in the data encoding, and the returned length is in characters, not bytes. See also ignorableWhitespace, which receiving notification about ignorable (whitespace formatting) character data.

Example <?xml version="1.0"?>
<doc><![CDATA [ stuff]]></doc>
  -SAX->
xmlDecl(version="1.0", encoding=NULL)
...
cdata(ch=" stuff", len=6)
...
See Also xmlinit, ignorableWhitespace

characters
Name characters
Interface SAX; SAX 1
Purpose Receives SAX notification of character data
Prototype sword (*characters)(void *ctx, const oratext *ch, size_t len);
Arguments
ctx (IN) user's SAX context [see xmlinit]
ch (IN) pointer to data [in data encoding]
len (IN) length of data [in characters]
Returns (sword) error code, XMLERR_OK [0] for success
Description This event marks character data, either Text or CDATA. If a cdata callback is provided, then CDATA will be send to that instead; with no cdata callback, both Text and CDATA go to the characters callback. The data will be in the data encoding, and the returned length is in characters, not bytes. See also ignorableWhitespace, which receiving notification about ignorable (whitespace formatting) character data.

Example <?xml version="1.0"?>
<top>junk</top>
  -SAX->
xmlDecl(version="1.0", encoding=NULL)
...
characters(ch="junk", len=4)
...
See Also xmlinit, ignorableWhitespace

comment
Name comment
Interface SAX; SAX 2
Purpose Receives SAX notification of a comment
Prototype sword (*comment)(void *ctx, const oratext *data);
Arguments
ctx (IN) user's SAX context [see xmlinit]
data (IN) comment's data [in data encoding]
Returns (sword) error code, XMLERR_OK [0] for success
Description This event marks a comment in the XML document. The comment's data will be in the data encoding.

Example <?xml version="1.0"?>
<!--Just a comment-->
<foo/>
  -SAX->
xmlDecl(version="1.0", encoding=NULL)
comment(data="Just a comment")
...
See Also xmlinit

elementDecl
Name elementDecl
Interface SAX; SAX X
Purpose Receives SAX notification of an element's declaration
Prototype sword (*elementDecl)(void *ctx, const oratext *name,const oratext *content);
Arguments
ctx (IN) user's SAX context [see xmlinit]
name (IN) element's name
content (IN) element's context model
Returns (sword) error code, XMLERR_OK [0] for success
Description This event marks an element declaration in the DTD. The element's name and content will be in the data encoding.

Example <?xml version="1.0"?>
<!DOCTYPE foo [
    <!ELEMENT e (#PCDATA)>
]>
...
  -SAX->
xmlDecl(version="1.0", encoding=NULL)
elementDecl(name="e", content="(#PCDATA)")
...
See Also xmlinit, attributeDecl

endDocument
Name endDocument
Interface SAX; SAX 1
Purpose Receives SAX end-of-document notification
Prototype sword (*endDocument)(void *ctx);
Arguments
ctx (IN) user's SAX context [see xmlinit]
Returns (sword) error code, XMLERR_OK [0] for success
Description The last SAX event, called once per document, indicating the end of the document. Matching event is startDocument.

Example <?xml version="1.0"?>
<top/>
  -SAX->
xmlDecl(version="1.0", encoding=NULL)
...
endDocument()
See Also xmlinit, startDocument

endElement
Name endElement
Interface SAX; SAX 1
Purpose Receives SAX end-of-element notification
Prototype sword (*endElement)(void *ctx, const oratext *name);
Arguments
ctx (IN) user's SAX context [see xmlinit]
name (IN) name of ending element [in data encoding]
Returns (sword) error code, XMLERR_OK [0] for success
Description This event marks the close of an element; it matches the startElement or startElementNS events. The name is the tagName of the element (which may be a QName for namespace-aware elements) and is in the data encoding.

Example <?xml version="1.0"?>
<top/>
  -SAX->
xmlDecl(version="1.0", encoding=NULL)
...
startElement(name="top", attrs=NULL)
endElement(name="top")
...
See Also xmlinit, endElement

ignorableWhitespace
Name ignorableWhitespace
Interface SAX; SAX 1
Purpose Receives SAX notification of ignorable (whitespace) data
Prototype sword (*ignorableWhitespace)(void *ctx, const oratext *ch, size_t len);
Arguments
ctx (IN) user's SAX context [see xmlinit]
ch (IN) pointer to data [in data encoding]
len (IN) length of data [in characters]
Returns (sword) error code, XMLERR_OK [0] for success
Description This event marks ignorable whitespace data such as newlines, and indentation between lines. The matching function is characters, which receives notification of normal character data. The data is in the data encoding, and the returned length is in characters, not bytes.

Example <?xml version="1.0"?>
<top>
    <sub>junk</sub>
</top>
  -SAX->
xmlDecl(version="1.0", encoding=NULL)
...
startElement(name="top", attrs=NULL)
ignorableWhitespace(ch="\n    ", len=5)
startElement(name="sub", attrs=NULL)
...
See Also xmlinit, characters

notationDecl
Name notationDecl
Interface SAX; SAX 1
Purpose Receives SAX notification of a notation declaration
Prototype sword (*notationDecl)(void *ctx, const oratext *name, 
                      const oratext *publicId, const oratext *systemId);
Arguments
ctx (IN) user's SAX context [see xmlinit]
name (IN) notation's name [in data encoding]
publicID (IN) notation's public ID [in data encoding] or NULL
systemID (IN) notation's system ID [in data encoding] or NULL
Returns (sword) error code, XMLERR_OK [0] for success
Description The even marks the declaration of a notation in the DTD. The notation's name, public ID, and system ID will all be in the data encoding. Both IDs are optional and may be NULL.

Example <?xml version="1.0"?>
<!DOCTYPE foo [
    <!NOTATION foo PUBLIC "[" "null.ent">
]>
...
  -SAX->
xmlDecl(version="1.0", encoding=NULL)
notationDecl(name="foo", publicID="[", systemID="null.ent")
See Also xmlinit

nsStartElement
Name nsStartElement
Interface SAX; SAX 2
Purpose Receives SAX namespace-aware start-of-element notification
Prototype sword (*nsStartElement)(void *ctx, const oratext *qname, 
                        const oratext *local, const oratext *nsp,
                        const struct xmlnodes *attrs);
Arguments
ctx (IN) user's SAX context [see xmlinit]
qname (IN) element's qualified name [in data encoding]
local (IN) element's namespace local name [in data encoding]
nsp (IN) element's namespace URI [in data encoding]
attrs (IN) NamedNodeMap of element's attributes, or NULL
Returns (sword) error code, XMLERR_OK [0] for success
Description This event marks the start of an element. Note this is the new SAX 2 namespace-aware version; startElement is the SAX 1 non-namespace-aware version. If both are registered, only the NS version will be called. The element's QName, local name, and namespace URI will be in the data encoding, as are all the attribute parts. See the functions in the NamedNodeMap interface for operating on the attributes map. The matching function is endElement (there is no endElementNS).

Example <?xml version="1.0"?>
<foo:top xmlns:foo="/foo/bar"/>
  -SAX->
xmlDecl(version="1.0", encoding=NULL)
...
startElement(qname="foo:top", local="top", nsp="/foo/bar", attrs=NULL)
endElement(name="foo:top")
...
See Also xmlinit, startElement

processingInstruction
Name processingInstruction
Interface SAX; SAX 1
Purpose Receives SAX notification of a processing instruction
Prototype sword (*processingInstruction)(void *ctx, const oratext *target, 
                               const oratext *data);
Arguments
ctx (IN) user's SAX context [see xmlinit]
target (IN) PI's target [in data encoding]
data (IN) PI's data [in data encoding] or NULL
Returns (sword) error code, XMLERR_OK [0] for success
Description This event marks a processing instruction. The PI's target and data will be in the data encoding. There is always a target, but the data may be NULL.

Example <?xml version="1.0"?>
<?keywords sax example?>
<top/>
  -SAX->
xmlDecl(version="1.0", encoding=NULL)
processingInstruction(target="keywords", data="sax example")
...
See Also xmlinit

startDocument
Name startDocument
Interface SAX; SAX 1
Purpose Receives SAX start-of document notification
Prototype sword (*startDocument)(void *ctx);
Arguments
ctx (IN) user's SAX context [see xmlinit]
Returns (sword) error code, XMLERR_OK [0] for success
Description The first SAX event, called once per document, indicating the start of the document. Matching event is endDocument.

Example <?xml version="1.0"?>
<top/>
  -SAX->
xmlDecl(version="1.0", encoding=NULL)
startDocument()
...
See Also xmlinit, endDocument

startElement
Name startElement
Interface SAX; SAX 1
Purpose Receives SAX start-of-element notification
Prototype sword (*startElement)(void *ctx, const oratext *name, 
                      const struct xmlnodes *attrs);
Arguments
ctx (IN) user's SAX context [see xmlinit]
name (IN) name of element [in data encoding]
attrs (IN) NamedNodeMap of element's attributes, or NULL
Returns (sword) error code, XMLERR_OK [0] for success
Description This event marks the start of an element. Note this is the original SAX 1 non-namespace-aware version; startElementNS is the SAX 2 namespace-aware version. If both are registered, only the NS version will be called. The element's name will be in the data encoding, as are all the attribute parts. See the functions in the NamedNodeMap interface for operating on the attributes map. The matching function is endElement (there is no endElementNS).

Example <?xml version="1.0"?>
<top/>
  -SAX->
xmlDecl(version="1.0", encoding=NULL)
...
startElement(name="top", attrs=NULL)
endElement(name="top")
...
See Also xmlinit, endElement, getNodeMapLength, getNamedItem, getChildNode

unparsedEntityDecl
Name unparsedEntityDecl
Interface SAX; SAX 1
Purpose Receives SAX notification of a unparsed entity declaration
Prototype sword (*unparsedEntityDecl)(void *ctx, const oratext *name, 
                            const oratext *publicId,
                            const oratext *systemId, 
                            const oratext *notationName);
Arguments
ctx (IN) user's SAX context [see xmlinit]
name (IN) entity's name [in data encoding]
publicID (IN) entity's public ID [in data encoding] or NULL
systemID (IN) entity's system ID [in data encoding]
notationName (IN) entity's notation name [in data encoding]
Returns (sword) error code, XMLERR_OK [0] for success
Description Marks an unparsed entity declaration in the DTD; there is no event for parsed entities. The unparsed entity's name, public ID, system ID, and notation name will all be in the data encoding.

Example <?xml version="1.0"?>
<!DOCTYPE foo [
    <!ENTITY e PUBLIC "p-p-pub-id" 'entity.dat' NDATA endayta>
]>
...
  -SAX->
xmlDecl(version="1.0", encoding=NULL)
unparsedEntityDecl(name="e", publicID="p-p-pub-id",
                   systemID="entity.dat", notationName="endayta")
See Also xmlinit

xmlDecl
Name xmlDecl
Interface SAX; SAX X
Purpose Receives SAX notification of an XML declaration
Prototype sword (*xmlDecl)(void *ctx, const oratext *version, boolean encoding);
Arguments
ctx (IN) user's SAX context [see xmlinit]
version (IN) version string from XMLDecl [in data encoding]
encoding (IN) encoding was specified?
Returns (sword) error code, XMLERR_OK [0] for success
Description This event marks an XML declaration (XMLDecl). The startDocument event is always first; if this callback is registered and an XMLDecl exists, it will be the second event. The encoding flag says whether an encoding was specified. Since the document's own encoding specification may be overridden, and the input will be converted to the data encoding anyway, the actual encoding specified is not provided. getEncoding returns the name of the data encoding.

Example <?xml version="1.0"?>
<top/>
  -SAX->
xmlDecl(version="1.0", encoding=FALSE)
...
See Also xmlinit, getEncoding