Skip Headers
Oracle® Database XML C API Reference
11g Release 2 (11.2)

Part Number E10770-02
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
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub
CAXML6144

11 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:

See Also:

CAXML6145

XML Interface

Table 11-1 summarizes the methods available through the XML interface.

CAXML6146Table 11-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.

XmlDiff()

Compares two XML documents.

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.


CAXML6147

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.

CAXML6148Syntax

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

CAXML6149Returns

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

CAXML6150

XmlCreate()

Create an XML Developer's Toolkit xmlctx.

CAXML6151Syntax

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. Properties common to all xmlctx's, both XDK and XMLType, are:
  • data_encoding is the data encoding in which XML data will be presented through DOM and SAX. Default is UTF-8 and UTF-E on EBCDIC platforms. Single-byte encodings are substantially faster than multibyte encodings; Unicode (UTF-16) uses more memory but has better performance than multibyte.

  • default_input_encoding is the default input encoding). If the encoding of an input document cannot be automatically determined through other methods, this encoding will be the default.

  • error_language is the language (and optional encoding) in which error messages are created. Default is American with UTF-8 encoding. To specify only the language, give the name of the language ("American"). To also specify the encoding, add the period and the Oracle name of the encoding ("American.WE8ISO8859P1").

  • error_handler is the function pointer; see XML_ERRMSG_F. By default, errors output the formatted message to stderr. If an error handler is provided, message will be passed to it, and not printed.

  • error_context is user-defined context for error handler, a context pointer to be passed to the error handler function. It is user-defined; it is just specified here and passed along when an error occurs.

  • input_encoding is the name of a forced input encoding for input documents. Use it to override a document's XMLDecl, and always interpret it in the given encoding. It should be not necessary in normal use, as existing BOMs and XMLDecls should be correct.

  • memory_alloc is a low-level memory allocation function, if not using malloc. If used, the matching free function must also be given. See XML_ALLOC_F.

  • memory_free is a low-level memory freeing function, if not using free. Matches the memory_alloc function.

  • memory_context is a user-defined memory context passed to the alloc and free functions. Its definition and use is entirely up to the user; it is just set here and passed to the callbacks.

The XDK has additional properties:

  • input_buffer_size is the basic I/O buffer size. Default is 256K; the range is 4K to 4MB. Depending on the encoding, 1, 2 or 3 of these buffers may be needed. Note that size is in characters, not bytes. If the buffer holds Unicode data, it will be twice as large.

  • memory_block_size is the size of chunk the high-level memory package will request from the low-level allocator; it is the basic unit of memory allocation. Default is 64K; the range is 16K to 256K.

These optional parameters should be used in the following manner:

xmlctx *XmlCreate(
   xmlerr *err, 
   oratext *name,
   ("data_encoding", dataEncoding),
   ("default_data_encoding", defaultDataEncoding),
   ("error_language", errorLanguage),
   ("error_handler", errorHandler),
   ("error_context", errorContext)
   ("input_encoding", inputEncoding),
   ("memory_alloc", memAlloc),
   ("memory_free", memFree),
   ("memory_context", memContext),
   ("input_buffer_seize", inputBufSize),
   ("memory_block_size", memBlockSize) );

CAXML6152Returns

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

CAXML6153

XmlCreateDTD()

Create DTD.

CAXML6154Syntax

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

CAXML6155Returns

(xmldtdnode *) new DTD node

CAXML6156

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.

CAXML6157Syntax

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

CAXML6158Returns

(xmldocnode *) new Document object.

CAXML6159

XmlDestroy()

Destroys an XML context.

CAXML6160Syntax

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

See Also:

XmlCreate()
CAXML6161

XmlDiff()

Compares two XML documents, specified either as DOM Trees, files, URIs, orastreams, and so on, and returns its document node. If input documents are not supplied as DOM trees, DOM trees will be created for them.

If the inputs are DOMs, that memory will not be freed when the call completes.

Data(DOM) encoding of both the documents must be the same as the data encoding in the XML context. The DOM for the diff will be created in the data encoding specified by the XML context.

CAXML6162Syntax

xmldocnode *XmlDiff(
   xmlctx *xctx, 
   xmlerr *err,
   ub4  flags,
   xmldfsrct firstSourceType,
   void *firstSource,
   void *firstSourceExtra,
   xmldfsrct secondSourceType,
   void *secondSource,
   void *secondSourceExtra,
   uword hashLevel);
Parameter In/Out Description
xctx
IN
XML context
err
OUT
numeric error code, XMLERR_OK [0] on success
flags
IN
Comparison options. By default, global algorithm and snapshot model are used.
  • XMLDF_FL_DEFAULTS(=0) chooses defaults

  • XMLDF_FL_ALGORITHM_GLOBAL is the global algorithm; it will generate the minimal diff using INSERT, APPEND, DELETE and UPDATE, and needs more memory and time than XMLDF_FL_ALGORITHM_LOCAL

  • XMLDF_FL_ALGORITHM_LOCAL is the local algorithm; it may not generate the minimal diff, but it is faster and uses less space than XMLDF_FL_ALGORITHM_GLOBAL

  • XMLDF_FL_DISABLE_UPDATE disables update operations with global algorithms

  • XMLDF_FL_OUTPUT_SNAPSHOT uses the snapshot model

firstSourceType
IN
Source type for the first document. If 0, assumed to be a DOM document node.
firstSource
IN
Pointer to the first document source
firstSourceExtra
IN
An additional pointer to the first document source; used for the buffer length pointer.
secondSourceType
IN
Source type for the second document. If 0, assumed to be a DOM document node.
secondSource
IN
Pointer to the second document source
secondSourceExtra
IN
An additional pointer to the second document source; used for the buffer length pointer.
hashLevel
IN
1-based depth (counting from the root), where hashing should be used for subtrees. Values less than or equal to 1 indicate no hashing. This value must be specified programmatically.

The hash value for every element node is associated with the entire subtree rooted at that node. During the computation of the diff, there is no further drilling down into the tree beyond hash level depth.

  • If hashing is used with XMLDF_FL_ALGORITHM_GLOBAL, it will speed up diff computation significantly, but may reduce the quality of the diff.

  • With XMLDF_FL_ALGORITHM_LOCAL, it improves the quality of the diff


CAXML6163

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.

CAXML6164Syntax

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

CAXML6165

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.

CAXML6166Syntax

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

CAXML6167Returns

(oratext *) name of data encoding

CAXML6168

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.

CAXML6169Syntax

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

CAXML6170Returns

(boolean) feature is implemented?

CAXML6171

XmlIsSimple()

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

CAXML6172Syntax

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

CAXML6173Returns

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

CAXML6174

XmlIsUnicode()

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

CAXML6175Syntax

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

CAXML6176Returns

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

CAXML6177

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:

CAXML6178Syntax

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

CAXML6179Returns

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

See Also:

XmlSaveDom()
CAXML6180

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.

CAXML6181Syntax

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

CAXML6182Returns

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

CAXML6183

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.

CAXML6184Syntax

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

CAXML6185Returns

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

CAXML6186

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:

CAXML6187Syntax

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

CAXML6188Returns

(ubig_ora) number of bytes written to destination

See Also:

XmlLoadDom()
CAXML6189

XmlVersion()

Returns the version string for the XDK

CAXML6190Syntax

oratext *XmlVersion();

CAXML6191Returns

(oratext *) version string

Reader Comment

   

Comments, corrections, and suggestions are forwarded to authors every week. By submitting, you confirm you agree to the terms and conditions. Use the OTN forums for product questions. For support or consulting, file a service request through My Oracle Support.

Hide Navigation

Quick Lookup

Database Library · Master Index · Master Glossary · Book List · Data Dictionary · SQL Keywords · Initialization Parameters · Advanced Search · Error Messages

Main Categories

This Page

  • XML Interface
    • XmlAccess()
    • XmlCreate()
    • XmlCreateDTD()
    • XmlCreateDocument()
    • XmlDestroy()
    • XmlDiff()
    • XmlFreeDocument()
    • XmlGetEncoding()
    • XmlHasFeature()
    • XmlIsSimple()
    • XmlIsUnicode()
    • XmlLoadDom()
    • XmlLoadSax()
    • XmlLoadSaxVA()
    • XmlSaveDom()
    • XmlVersion()

This Document

New and changed documents:
RSS Feed HTML RSS Feed PDF