Skip Headers

Oracle® XML API Reference
10g Release 1 (10.1)
Part No. B10789-01
  Go To Table Of Contents
Contents

Previous Next  

SAX Interface

Table 6-1 summarizes the methods of available through the SAX interface.

Table 6-1 Summary of SAX Methods

Function Summary
XmlSaxAttributeDecl
Receives SAX notification of an attribute's declaration. Oracle
XmlSaxCDATA
Receives SAX notification of CDATA. Oracle extension.
XmlSaxCharacters
Receives SAX notification of character data
XmlSaxComment
Receives SAX notification of a comment.
XmlSaxElementDecl
Receives SAX notification of an element's declaration. Oracle extension.
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 extension.
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 an unparsed entity declaration.
XmlSaxWhitespace
Receives SAX notification of ignorable (whitespace) data.
XmlSaxXmlDecl
Receives SAX notification of an XML declaration. Oracle extension.


XmlSaxAttributeDecl

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!


Syntax
xmlerr XmlSaxAttributeDecl(
   void *ctx, 
   oratext *elem, 
   oratext *attr, 
   oratext *body)

Parameter In/Out Description
ctx
IN
user's SAX context
elem
IN
element for which the attribute is declared; data encoding
attr
IN
attribute's name; data encoding
body
IN
body of an attribute declaration


Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxCDATA

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.


Syntax
xmlerr XmlSaxCDATA(
   void *ctx, 
   oratext *ch, 
   size_t len)

Parameter In/Out Description
ctx
IN
user's SAX context
ch
IN
pointer to CDATA; data encoding
len
IN
length of CDATA, in characters


Returns

(xmlerr) error code, XMLERR_OK [0] for success


See Also:

XmlSaxWhitespace


XmlSaxCharacters

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.


Syntax
xmlerr XmlSaxCharacters(
   void *ctx, 
   oratext *ch, 
   size_t len)

Parameter In/Out Description
ctx
IN
user's SAX context
ch
IN
pointer to data; data encoding
len
IN
length of data, in characters


Returns

(xmlerr) error code, XMLERR_OK [0] for success


See Also:

XmlSaxWhitespace


XmlSaxComment

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.


Syntax
xmlerr XmlSaxComment(
   void *ctx, 
   oratext *data)

Parameter In/Out Description
ctx
IN
user's SAX context
data
IN
comment's data; data encoding


Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxElementDecl

This event marks an element declaration in the DTD. The element's name and content will be in the data encoding.


Syntax
xmlerr XmlSaxElementDecl(
   void *ctx, 
   oratext *name, 
   oratext *content)

Parameter In/Out Description
ctx
IN
user's SAX context
name
IN
element's name
content
IN
element's context model


Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxEndDocument

The last SAX event, called once for each document, indicating the end of the document. Matching event is XmlSaxStartDocument.


Syntax
xmlerr XmlSaxEndDocument(
   void *ctx)

Parameter In/Out Description
ctx
IN
user's SAX context


Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxEndElement

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 qualified name for namespace-aware elements) and is in the data encoding.


Syntax
xmlerr XmlSaxEndElement(
   void *ctx, 
   oratext *name)

Parameter In/Out Description
ctx
IN
user's SAX context
name
IN
name of ending element; data encoding


Returns

(xmlerr) error code, XMLERR_OK [0] for success


See Also:

XmlSaxEndElement


XmlSaxNotationDecl

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.


Syntax
xmlerr XmlSaxNotationDecl(
   void *ctx, 
   oratext *name, 
   oratext *pubId, 
   oratext *sysId)

Parameter In/Out Description
ctx
IN
user's SAX context
name
IN
notation's name; data encoding
pubId
IN
notation's public ID as data encoding, or NULL
sysId
IN
notation's system ID as data encoding, or NULL


Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxPI

This event marks a ProcessingInstruction. The ProcessingInstructions target and data will be in the data encoding. There is always a target, but the data may be NULL.


Syntax
xmlerr XmlSaxPI(
   void *ctx, 
   oratext *target, 
   oratext *data)

Parameter In/Out Description
ctx
IN
user's SAX context
target
IN
PI's target; data encoding
data
IN
PI's data as data encoding, or NULL


Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxParsedEntityDecl

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.


Syntax
xmlerr XmlSaxParsedEntityDecl(
   void *ctx, 
   oratext *name, 
   oratext *value, 
   oratext *pubId, 
   oratext *sysId, 
   boolean general)

Parameter In/Out Description
ctx
IN
user's SAX context
name
IN
entity's name; data encoding
value
IN
entity's value; data encoding
pubId
IN
entity's public ID as data encoding, or NULL
sysId
IN
entity's system ID; data encoding
general
IN
TRUE if general entity, FALSE if parameter entity


Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxStartDocument

The first SAX event, called once for each document, indicating the start of the document. Matching event is XmlSaxEndDocument.


Syntax
xmlerr XmlSaxStartDocument(
   void *ctx)

Parameter In/Out Description
ctx
IN
user's SAX context


Returns

(xmlerr) error code, XMLERR_OK [0] for success


See Also:

XmlSaxEndDocument


XmlSaxStartElement

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 namespace aware version of this function).


Syntax
xmlerr XmlSaxStartElement(
   void *ctx, 
   oratext *name, 
   xmlnodelist *attrs)

Parameter In/Out Description
ctx
IN
user's SAX context
name
IN
element's name; data encoding
attrs
IN
NamedNodeMap of element's attributes


Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxStartElementNS

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 qualified name, 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 namespace aware version of this function).


Syntax
xmlerr XmlSaxStartElementNS(
   void *ctx, 
   oratext *qname, 
   oratext *local, 
   oratext *nsp, 
   xmlnodelist *attrs)

Parameter In/Out Description
ctx
IN
user's SAX context
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


XmlSaxUnparsedEntityDecl

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.


Syntax
xmlerr XmlSaxUnparsedEntityDecl(
   void *ctx, 
   oratext *name, 
   oratext *pubId, 
   oratext *sysId, 
   oratext *note)

Parameter In/Out Description
ctx
IN
user's SAX context
name
IN
entity's name; data encoding
pubId
IN
entity's public ID as 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


XmlSaxWhitespace

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.


Syntax
xmlerr XmlSaxWhitespace(
   void *ctx, 
   oratext *ch, 
   size_t len)

Parameter In/Out Description
ctx
IN
user's SAX context
ch
IN
pointer to data; data encoding
len
IN
length of data, in characters


Returns

(xmlerr) error code, XMLERR_OK [0] for success


See Also:

XmlSaxCharacters


XmlSaxXmlDecl

This event marks an XML declaration. 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.


Syntax
xmlerr XmlSaxXmlDecl(
   void *ctx, 
   oratext *version, 
   boolean encoding, 
   sword standalone)

Parameter In/Out Description
ctx
IN
user's SAX context
version
IN
version string from XMLDecl; data encoding
encoding
IN
whether encoding was specified
standalone
IN
value of the standalone document; < 0 if not specified


Returns

(xmlerr) error code, XMLERR_OK [0] for success