Packages: All | Callback | DOM | Range | SAX | Schema | Traversal | XML | XPath | XPointer | XSLT | XSLTVM 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 one of the XmlLoadSax calls. A pointer to a user-defined context structure is also provided, and will be passed to each SAX function.


Interface SAX

Function Index

FunctionDescription
XmlSaxAttributeDecl Receives SAX notification of an attribute's declaration. Oracle
XmlSaxCDATA Receives SAX notification of CDATA. Oracle extension, not in SAX
XmlSaxCharacters Receives SAX notification of character data
XmlSaxComment Receives SAX notification of a comment
XmlSaxElementDecl Receives SAX notification of an element's declaration. Oracle
XmlSaxEndDocument Receives SAX end-of-document notification
XmlSaxEndElement Receives SAX end-of-element notification
XmlSaxNotationDecl Receives SAX notification of a notation declaration
XmlSaxPI Receives SAX notification of a processing instruction
XmlSaxParsedEntityDecl Receives SAX notification of a parsed entity declaration. Oracle
XmlSaxStartDocument Receives SAX start-of document notification
XmlSaxStartElement Receives SAX start-of-element notification
XmlSaxStartElementNS Receives SAX namespace-aware start-of-element notification
XmlSaxUnparsedEntityDecl Receives SAX notification of a unparsed entity declaration
XmlSaxWhitespace Receives SAX notification of ignorable (whitespace) data
XmlSaxXmlDecl Receives SAX notification of an XML declaration. Oracle extension,

XmlSaxAttributeDecl

Name XmlSaxAttributeDecl
Interface SAX
Purpose Receives SAX notification of an attribute's declaration. Oracle
Prototype xmlerr XmlSaxAttributeDecl(void *ctx, oratext *elem, oratext *attr, oratext *body)
Arguments
ctx  (IN)  user's SAX context [see XmlLoadSax functions]
elem  (IN)  element that attribute is declared for [data encoding]
attr  (IN)  attribute's name [data encoding]
body  (IN)  body of attribute declaration [data encoding]
Returns (xmlerr) 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 <!DOCTYPE foo [ <!ATTLIST a id ID #IMPLIED> ]>
...
  --SAX Parse-->
XmlSaxAttributeDecl(elem="a", name="id", body="ID #IMPLIED")
...
See Also XmlSaxAttributeDecl

XmlSaxCDATA

Name XmlSaxCDATA
Interface SAX
Purpose Receives SAX notification of CDATA. Oracle extension, not in SAX
Prototype xmlerr XmlSaxCDATA(void *ctx, oratext *ch, size_t len)
Arguments
ctx  (IN)  user's SAX context [see XmlLoadSax functions]
ch  (IN)  pointer to CDATA [data encoding]
len  (IN)  length of CDATA [in characters]
Returns (xmlerr) error code, XMLERR_OK [0] for success
Description This event handles CDATA, as distinct from Text. If no XmlSaxCDATA 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 XmlSaxWhitespace, which receiving notification about ignorable (whitespace formatting) character data.

Example <doc><![CDATA [ stuff]]></doc>
  --SAX Parse-->
...
XmlSaxCDATA(ch=" stuff", len=6)
...
See Also XmlSaxWhitespace

XmlSaxCharacters

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

Example <top>junk</top>
  --SAX Parse-->
...
XmlSaxCharacters(ch="junk", len=4)
...
See Also XmlSaxWhitespace

XmlSaxComment

Name XmlSaxComment
Interface SAX
Purpose Receives SAX notification of a comment
Prototype xmlerr XmlSaxComment(void *ctx, oratext *data)
Arguments
ctx  (IN)  user's SAX context [see XmlLoadSax functions]
data  (IN)  comment's data [data encoding]
Returns (xmlerr) 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. Oracle extension, not in SAX standard.

Example <!--Just a comment-->
<foo/>
  --SAX Parse-->
XmlSaxComment(data="Just a comment")
...

XmlSaxElementDecl

Name XmlSaxElementDecl
Interface SAX
Purpose Receives SAX notification of an element's declaration. Oracle
Prototype xmlerr XmlSaxElementDecl(void *ctx, oratext *name, oratext *content)
Arguments
ctx  (IN)  user's SAX context [see XmlLoadSax functions]
name  (IN)  element's name
content  (IN)  element's context model
Returns (xmlerr) 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 <!DOCTYPE foo [ <!ELEMENT e (#PCDATA)> ]>
...
  --SAX Parse-->
XmlSaxElementDecl(name="e", content="(#PCDATA)")
...
See Also XmlSaxAttributeDecl

XmlSaxEndDocument

Name XmlSaxEndDocument
Interface SAX; SAX 2: ContentHandler.endDocument()
Purpose Receives SAX end-of-document notification
Prototype xmlerr XmlSaxEndDocument(void *ctx)
Arguments
ctx  (IN)  user's SAX context [see XmlLoadSax functions]
Returns (xmlerr) 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 XmlSaxStartDocument.

Example <top/>
  --SAX Parse-->
...
XmlSaxEndDocument()
See Also XmlSaxStartDocument

XmlSaxEndElement

Name XmlSaxEndElement
Interface SAX; SAX 1: DocumentHandler.endElement()
Purpose Receives SAX end-of-element notification
Prototype xmlerr XmlSaxEndElement(void *ctx, oratext *name)
Arguments
ctx  (IN)  user's SAX context [see XmlLoadSax functions]
name  (IN)  name of ending element [data encoding]
Returns (xmlerr) error code, XMLERR_OK [0] for success
Description This event marks the close of an element; it matches the XmlSaxStartElement or XmlSaxStartElementNS 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 <top/>
  --SAX Parse-->
...
XmlSaxStartElement(name="top", attrs=NULL)
XmlSaxEndElement(name="top")
...
See Also XmlSaxEndElement

XmlSaxNotationDecl

Name XmlSaxNotationDecl
Interface SAX; SAX 1: DTDHandler.notationDecl()
Purpose Receives SAX notification of a notation declaration
Prototype xmlerr XmlSaxNotationDecl(void *ctx, oratext *name, oratext *pubId, oratext *sysId)
Arguments
ctx  (IN)  user's SAX context [see XmlLoadSax functions]
name  (IN)  notation's name [data encoding]
publicID  (IN)  notation's public ID [data encoding] or NULL
systemID  (IN)  notation's system ID [data encoding] or NULL
Returns (xmlerr) 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 <!DOCTYPE foo [ <!NOTATION foo PUBLIC "[" "null.ent"> ]>
...
  --SAX Parse-->
XmlSaxNotationDecl(name="foo", publicID="[", systemID="null.ent")
...

XmlSaxPI

Name XmlSaxPI
Interface SAX; SAX 2: ContentHandler.processingInstruction()
Purpose Receives SAX notification of a processing instruction
Prototype xmlerr XmlSaxPI(void *ctx, oratext *target, oratext *data)
Arguments
ctx  (IN)  user's SAX context [see XmlLoadSax functions]
target  (IN)  PI's target [data encoding]
data  (IN)  PI's data [data encoding] or NULL
Returns (xmlerr) 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 <?keywords sax example?>
<top/>
  --SAX Parse-->
XmlSaxPI(target="keywords", data="sax example")
...

XmlSaxParsedEntityDecl

Name XmlSaxParsedEntityDecl
Interface SAX
Purpose Receives SAX notification of a parsed entity declaration. Oracle
Prototype xmlerr XmlSaxParsedEntityDecl(void *ctx, oratext *name, oratext *value, 
                             oratext *pubId, oratext *sysId, boolean general)
Arguments
ctx  (IN)  user's SAX context [see XmlLoadSax functions]
name  (IN)  entity's name [data encoding]
value  (IN)  entity's value if internal [data encoding]
pubId  (IN)  entity's public ID [data encoding] or NULL
sysId  (IN)  entity's system ID [data encoding]
general  (IN)  general entity? FALSE if parameter entity
Returns (xmlerr) error code, XMLERR_OK [0] for success
Description Marks an parsed entity declaration in the DTD. The parsed 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 e1 "foobar">
    <!ENTITY e2 SYSTEM "nop.ent">
    <!ENTITY % e3 "parameter_entity_value">
]>
...
  --SAX Parse-->
XmlSaxXmlDecl(version="1.0", encoding=NULL)
XmlSaxParsedEntityDecl(name="e1", value="foobar", pubID=NULL,
                         sysID=NULL, general=TRUE)
XmlSaxParsedEntityDecl(name="e2", value=NULL, pubID=NULL,
                         sysID="nop.ent", general=TRUE)
XmlSaxParsedEntityDecl(name="32", value="parameter_entity_value",
                        pubID=NULL, sysID=NULL, general=FALSE)
...
See Also XmlSaxUnparsedEntityDecl

XmlSaxStartDocument

Name XmlSaxStartDocument
Interface SAX; SAX 2: ContentHandler.startDocument()
Purpose Receives SAX start-of document notification
Prototype xmlerr XmlSaxStartDocument(void *ctx)
Arguments
ctx  (IN)  user's SAX context [see XmlLoadSax functions]
Returns (xmlerr) 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 XmlSaxEndDocument.

Example <top/>
  --SAX Parse-->
XmlSaxStartDocument()
...
See Also XmlSaxEndDocument

XmlSaxStartElement

Name XmlSaxStartElement
Interface SAX; SAX 1: DocumentHandler.startElement()
Purpose Receives SAX start-of-element notification
Prototype xmlerr XmlSaxStartElement(void *ctx, oratext *name, xmlnodelist *attrs)
Arguments
ctx  (IN)  user's SAX context [see XmlLoadSax functions]
name  (IN)  name of element [data encoding]
attrs  (IN)  NamedNodeMap of element's attributes, or NULL
Returns (xmlerr) 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; XmlSaxStartElementNS 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 XmlSaxEndElement (there is no XmlSaxEndElementNS).

Example <top/>
  --SAX Parse-->
...
XmlSaxStartElement(name="top", attrs=NULL)
XmlSaxEndElement(name="top")
...
See Also XmlSaxEndElement, XmlDomGetNodeMapLength, XmlDomGetNamedItem

XmlSaxStartElementNS

Name XmlSaxStartElementNS
Interface SAX; SAX 2: ContentHandler.startElement()
Purpose Receives SAX namespace-aware start-of-element notification
Prototype xmlerr XmlSaxStartElementNS(void *ctx, oratext *qname, oratext *local, 
                           oratext *nsp, xmlnodelist *attrs)
Arguments
ctx  (IN)  user's SAX context [see XmlLoadSax functions]
qname  (IN)  element's qualified name [data encoding]
local  (IN)  element's namespace local name [data encoding]
nsp  (IN)  element's namespace URI [data encoding]
attrs  (IN)  NodeList of element's attributes, or NULL
Returns (xmlerr) 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; XmlSaxStartElement 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 XmlSaxEndElement (there is no XmlSaxEndElementNS).

Example <foo:top xmlns:foo="/foo/bar"/>
  --SAX Parse-->
...
XmlSaxStartElement(qname="foo:top", local="top",
                   nsp="/foo/bar", attrs=NULL)
XmlSaxEndElement(name="foo:top")
...
See Also XmlSaxStartElement, XmlSaxEndElement, XmlDomGetNodeMapLength, XmlDomGetNamedItem

XmlSaxUnparsedEntityDecl

Name XmlSaxUnparsedEntityDecl
Interface SAX; SAX 1: DTDHandler.unparsedEntityDecl()
Purpose Receives SAX notification of a unparsed entity declaration
Prototype xmlerr XmlSaxUnparsedEntityDecl(void *ctx, oratext *name, oratext *pubId, oratext *sysId, 
                               oratext *note)
Arguments
ctx  (IN)  user's SAX context [see XmlLoadSax functions]
name  (IN)  entity's name [data encoding]
pubId  (IN)  entity's public ID [data encoding] or NULL
sysId  (IN)  entity's system ID [data encoding]
note  (IN)  entity's notation name [data encoding]
Returns (xmlerr) error code, XMLERR_OK [0] for success
Description Marks an unparsed entity declaration in the DTD, see XmlSaxParsedEntityDecl for the parsed entity version. The unparsed entity's name, public ID, system ID, and notation name will all be in the data encoding.

Example <!DOCTYPE foo [
    <!ENTITY e PUBLIC "p-p-pub-id" 'entity.dat' NDATA endayta>
]>
...
  --SAX Parse-->
XmlSaxUnparsedEntityDecl(name="e", publicID="p-p-pub-id",
                         systemID="entity.dat", notationName="endayta")
See Also XmlSaxParsedEntityDecl

XmlSaxWhitespace

Name XmlSaxWhitespace
Interface SAX; SAX 2: ContentHandler.ignorableWhitespace()
Purpose Receives SAX notification of ignorable (whitespace) data
Prototype xmlerr XmlSaxWhitespace(void *ctx, oratext *ch, size_t len)
Arguments
ctx  (IN)  user's SAX context [see XmlLoadSax functions]
ch  (IN)  pointer to data [data encoding]
len  (IN)  length of data [in characters]
Returns (xmlerr) 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 XmlSaxCharacters, which receives notification of normal character data. The data is in the data encoding, and the returned length is in characters, not bytes.

Example <top>
    <sub>junk</sub>
</top>
  --SAX Parse-->
...
XmlSaxStartElement(name="top", attrs=NULL)
XmlSaxWhitespace(ch="\n    ", len=5)
XmlSaxStartElement(name="sub", attrs=NULL)
...
See Also XmlSaxCharacters

XmlSaxXmlDecl

Name XmlSaxXmlDecl
Interface SAX
Purpose Receives SAX notification of an XML declaration. Oracle extension,
Prototype xmlerr XmlSaxXmlDecl(void *ctx, oratext *version, boolean encoding, sword standalone)
Arguments
ctx  (IN)  user's SAX context [see XmlLoadSax functions]
version  (IN)  version string from XMLDecl [data encoding]
encoding  (IN)  encoding was specified?
standalone  (IN)  value of standalone-document flag [< 0 not specified]
Returns (xmlerr) error code, XMLERR_OK [0] for success
Description This event marks an XML declaration (XMLDecl). The XmlSaxStartDocument 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 (or wrong), and the input will be converted to the data encoding anyway, the actual encoding specified in the document is not provided. For the standalone flag, -1 will be returned if it was not specified, otherwise 0 for FALSE, 1 for TRUE.

Example <?xml version="1.0"?>
<top/>
  --SAX Parse-->
XmlSaxXmlDecl(version="1.0", encoding=FALSE)
...