Skip Headers

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

Previous Next  

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


See Also:

XmlLoadDom, XmlLoadSax


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