Skip Headers
Oracle® Database XML C API Reference
10g Release 2 (10.2)

Part Number B16207-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

9 Package XML APIs for C

This C implementation of the XML processor (or parser) follows the W3C XML specification (rev REC-xml-19980210) and implements the required behavior of an XML processor in terms of how it must read XML data and the information it must provide to the application.

This chapter contains the following section:


XML Interface

Table 9-1 summarizes the methods of available through the XML interface.

Table 9-1 Summary of XML Methods

Function Summary
XmlAccess()
Set access method callbacks for URL.
XmlCreate()
Create an XML Developer's Toolkit xmlctx.
XmlCreateDTD()
Create DTD.
XmlCreateDocument()
Create Document (node).
XmlDestroy()
Destroy an xmlctx.
XmlFreeDocument()
Free a document (releases all resources).
XmlGetEncoding()
Returns data encoding in use by XML context.
XmlHasFeature()
Determine if DOM feature is implemented.
XmlIsSimple()
Returns single-byte (simple) characterset flag.
XmlIsUnicode()
Returns XmlIsUnicode (simple) characterset flag.
XmlLoadDom()
Load (parse) an XML document and produce a DOM.
XmlLoadSax()
Load (parse) an XML document from and produce SAX events.
XmlLoadSaxVA()
Load (parse) an XML document from and produce SAX events [varargs].
XmlSaveDom()
Saves (serializes, formats) an XML document.
XmlVersion()
Returns version string for XDK.


XmlAccess()

Sets the open/read/close callbacks used to load data for a specific URL access method. Overrides the built-in data loading functions for HTTP, FTP, and so on, or provides functions to handle new types, such as UNKNOWN.

Syntax

xmlerr XmlAccess(
   xmlctx *xctx, 
   xmlurlacc access, 
   void *userctx,
   XML_ACCESS_OPEN_F(
      (*openf),
      ctx,
      uri,
      parts,
      length,
      uh),
   XML_ACCESS_READ_F(
      (*readf),
      ctx,
      uh,
      data,
      nraw,
      eoi),
   XML_ACCESS_CLOSE_F(
      (*closef), 
      ctx,
      uh));
Parameter In/Out Description
xctx
IN
XML context
access
IN
URL access method
userctx
IN
user-defined context passed to callbacks
openf
IN
open-access callback function
readf
IN
read-access callback function
closef
IN
close-access callback function

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlCreate()

Create an XML Developer's Toolkit xmlctx. Properties common to all xmlctx's (both XDK and XMLType) are:

Syntax

xmlctx *XmlCreate(
   xmlerr *err, 
   oratext *name,
   list);
Parameter In/Out Description
err
OUT
returned error code
access
IN
name of context, for debugging
list
IN
NULL-terminated list of variable arguments

Returns

(xmlctx *) created xmlctx [or NULL on error with err set]


XmlCreateDTD()

Create DTD.

Syntax

xmldocnode* XmlCreateDTD(
   xmlctx *xctx
   oratext *qname,
   oratext *pubid,
   oratext *sysid,
   xmlerr *err);
Parameter In/Out Description
xctx
IN
XML context
qname
IN
qualified name
pubid
IN
external subset public identifier
sysid
IN
external subset system identifier
err
OUT
returned error code

Returns

(xmldtdnode *) new DTD node


XmlCreateDocument()

Creates the initial top-level DOCUMENT node and its supporting infrastructure. If a qualified name is provided, a an element with that name is created and set as the document's root element.

Syntax

xmldocnode* XmlCreateDocument(
   xmlctx *xctx,
   oratext *uri,
   oratext *qname, 
   xmldtdnode *dtd,
   xmlerr *err);
Parameter In/Out Description
xctx
IN
XML context
uri
IN
namespace URI of root element to create, or NULL
qname
IN
qualified name of root element, or NULL if none
dtd
IN
associated DTD node
err
OUT
returned error code

Returns

(xmldocnode *) new Document object.


XmlDestroy()

Destroys an xmlctx

Syntax

void XmlDestroy(
   xmlctx *xctx);
Parameter In/Out Description
xctx
IN
XML context


See Also:

XmlCreate()


XmlFreeDocument()

Destroys a document created by XmlCreateDocument or through one of the Load functions. Releases all resources associated with the document, which is then invalid.

Syntax

void XmlFreeDocument(
   xmlctx *xctx,
   xmldocnode *doc);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
document to free


XmlGetEncoding()

Returns data encoding in use by XML context. Ordinarily, the data encoding is chosen by the user, so this function is not needed. However, if the data encoding is not specified, and allowed to default, this function can be used to return the name of that default encoding.

Syntax

oratext *XmlGetEncoding(
   xmlctx *xctx);
Parameter In/Out Description
xctx
IN
XML context

Returns

(oratext *) name of data encoding


XmlHasFeature()

Determine if a DOM feature is implemented. Returns TRUE if the feature is implemented in the specified version, FALSE otherwise.

In level 1, the legal values for package are 'HTML' and 'XML' (case-insensitive), and the version is the string "1.0". If the version is not specified, supporting any version of the feature will cause the method to return TRUE.

Syntax

boolean XmlHasFeature(
   xmlctx *xctx,
   oratext *feature,
   oratext *version);
Parameter In/Out Description
xctx
IN
XML context
feature
IN
package name of the feature to test
version
IN
version number of the package name to test

Returns

(boolean) feature is implemented?


XmlIsSimple()

Returns a flag saying whether the context's data encoding is "simple", single-byte for each character, like ASCII or EBCDIC.

Syntax

boolean XmlIsSimple(
   xmlctx *xctx);
Parameter In/Out Description
xctx
IN
XML context

Returns

(boolean) TRUE of data encoding is "simple", FALSE otherwise


XmlIsUnicode()

Returns a flag saying whether the context's data encoding is Unicode, UTF-16, with two-byte for each character.

Syntax

boolean XmlIsUnicode(
   xmlctx *xctx);
Parameter In/Out Description
xctx
IN
XML context

Returns

(boolean) TRUE of data encoding is Unicode, FALSE otherwise


XmlLoadDom()

Loads (parses) an XML document from an input source and creates a DOM. The root document node is returned on success, or NULL on failure (with err set).

The function takes two fixed arguments, the xmlctx and an error return code, then zero or more (property, value) pairs, then NULL.

SOURCE Input source is set by one of the following mutually exclusive properties (choose one):

PROPERTIES Additional properties:

Syntax

xmldocnode *XmlLoadDom(
   xmlctx *xctx, 
   xmlerr *err, 
   list);
Parameter In/Out Description
xctx
IN
XML context
err
OUT
returned error code
list
IN
NULL-terminated list of variable arguments

Returns

(xmldocnode *) document node on success [NULL on failure with err set]


See Also:

XmlSaveDom()


XmlLoadSax()

Loads (parses) an XML document from an input source and generates a set of SAX events (as user callbacks). Input sources and basic set of properties is the same as for XmlLoadDom.

Syntax

xmlerr XmlLoadSax(
   xmlctx *xctx,
   xmlsaxcb *saxcb,
   void *saxctx, 
   list);
Parameter In/Out Description
xctx
IN
XML context
saxcb
IN
SAX callback structure
saxctx
IN
context passed to SAX callbacks
list
IN
NULL-terminated list of variable arguments

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlLoadSaxVA()

Loads (parses) an XML document from an input source and generates a set of SAX events (as user callbacks). Input sources and basic set of properties is the same as for XmlLoadDom.

Syntax

xmlerr XmlLoadSaxVA(
   xmlctx *xctx, 
   xmlsaxcb *saxcb, 
   void *saxctx, 
   va_list va);
Parameter In/Out Description
xctx
IN
XML context
saxcb
IN
SAX callback structure
saxctx
IN
context passed to SAX callbacks
va
IN
NULL-terminated list of variable arguments

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlSaveDom()

Serializes document or subtree to the given destination and returns the number of bytes written; if no destination is provided, just returns formatted size but does not output.

If an output encoding is specified, the document will be re-encoded on output; otherwise, it will be in its existing encoding.

The top level is indented step*level spaces, the next level step*(level+1) spaces, and so on.

When saving to a buffer, if the buffer overflows, 0 is returned and err is set to XMLERR_SAVE_OVERFLOW.

DESTINATION Output destination is set by one of the following mutually exclusive properties (choose one):

PROPERTIES Additional properties:

Syntax

ubig_ora XmlSaveDom(
   xmlctx *xctx,
   xmlerr *err,
   xmlnode *root,
   list);
Parameter In/Out Description
xctx
IN
XML context
err
OUT
error code on failure
root
IN
root node or subtree to save
list
IN
NULL-terminated list of variable arguments

Returns

(ubig_ora) number of bytes written to destination


See Also:

XmlLoadDom()


XmlVersion()

Returns the version string for the XDK

Syntax

oratext *XmlVersion();

Returns

(oratext *) version string