13
XML Parser for C

This chapter describes the following sections:

• Parser APIs
• W3C SAX APIs
• W3C DOM APIs
• Namespace APIs

  See Also: Oracle9i XML Developer's Kits Guide - XDK

---

Parser APIs

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.

---

Calling Sequence

Parsing a single document:

xmlinit, xmlparsexxx, xmlterm

Parsing multiple documents, but only the latest document's data needs to be available:

xmlinit, xmlparsexxx, xmlclean, xmlparsexxx, xmlclean ... xmlterm

Parsing multiple documents, all document data must be available:

xmlinit, xmlparsexxx, xmlparsexxx ... xmlterm

---

Memory

Memory callback functions may be used if you wish to use your own memory allocation. If they are used, both functions should be specified.

The memory allocated for parameters passed to the SAX callbacks or for nodes and data stored with the DOM parse tree will not be freed until one of the following is done:

• xmlclean() is called.
• xmlterm() is called.

---

Thread Safety

If threads are forked off somewhere in the midst of the init-parse-terminate sequence of calls, you will get unpredictable behavior and results.

---

Data Types

Table 13-1 Summary of Data Types for Parser APIs  

Data Type	Syntax	Description
boolean	typedef int boolean;	Boolean value, TRUE or FALSE.
oratext	typedef unsigned char oratext;	String pointer used for all data encodings, cast as needed; for UTF-16, to (ub2 *)
string	typedef unsigned char String;	String pointer (C/C++)
ub4	typedef unsigned int ub4;	32-bit (or larger) unsigned integer
uword	typedef unsigned int uword;	Native unsigned integer
xmlacctype	XMLACCESS_UNK /*An access method was specified an a URL, but it was unknown to the XML parser*/ XMLACCESS_FILE /*Filesystem I/O*/ XMLACCESS_HTTP /*HyperText Transport Protocol; the Web)*/ XMLACCESS_FTP /*File Transfer Protocol */ XMLACCESS_GOPHER /*Gopher*/ XMLACCESS_ORADB /*Direct Oracle database access*/ XMLACCESS_STREAM /*User-defined stream*/	An enumeration of the possible access methods used to retrieve an XML document XML access type, like HTTP, FTP, File, and so on. See the xmlaccess() function for more details.
xmlctx	typedef struct xmlctx xmlctx;	Top-level XML context; the contents of xmlctx are private and must not be accessed by users.
xmlmemcb	struct xmlmemcb { void *(*alloc)(void *ctx, size_t size); void (*free)(void *ctx, void *ptr); }; typedef struct xmlmemcb xmlmemcb;	Memory callback structure (optional). This is the memory callback structure. Allocations do not need to be initialized; works like malloc, not calloc.
xmlnode	typedef struct xmlnode xmlnode;	Note: The contents of xmlnode are private and must not be accessed by users.
xmlntype	ELEMENT_NODE = 1 /* element */ ATTRIBUTE_NODE= 2 /* attribute */ TEXT_NODE = 3 /* char data not escaped by CDATA */ CDATA_SECTION_NODE= 4 /* char data escaped by CDATA */ ENTITY_REFERENCE_NODE = 5 /* entity reference */ ENTITY_NODE = 6 /* entity */ PROCESSING_INSTRUCTION_NODE = 7 /* processing instruction */ COMMENT_NODE= 8 /* comment */ DOCUMENT_NODE = 9 /* document */ DOCUMENT_TYPE_NODE= 10 /* DTD */ DOCUMENT_FRAGMENT_NODE= 11 /* document fragment */ NOTATION_NODE = 12 /* notation */	Node type enumeration Parse tree node types, see getNodeType(). Names and values match DOM specification.
xmlsaxc	struct xmlsaxcb { sword (*startDocument) (void *ctx); sword (*endDocument) (void *ctx); sword (*startElement)(void *ctx, const oratext *name, const struct xmlattrs *attrs); sword (*endElement)(void *ctx, const oratext *name); sword (*characters)(void *ctx, const oratext *ch, size_t len); sword (*ignorableWhitespace)(void *ctx, const oratext *ch, size_t len); sword (*processingInstruction)(void *ctx, const oratext *target, const oratext *data); sword (*notationDecl)(void *ctx, const oratext *name, const oratext *publicId, const oratext *systemId); sword (*unparsedEntityDecl)(void *ctx, const oratext *name, const oratext *publicId, const oratext *systemId, const oratext *notationName); sword (*comment)(void *ctx, const oratext *data); sword (*elementDecl)(void *ctx, const oratext *name, const oratext *content); sword (*attributeDecl)(void *ctx, const oratext *elem, const oratext *attr, const oratext *body); sword (*xmlDecl)(void *ctx, const oratext *version, boolean encoding); /* Following fields are reserved for future use.*/ void (*empty1)(); void (*empty2)(); void (*empty3)(); void (*empty4)(); }; typedef struct xmlsaxcb xmlsaxcb;	SAX callback structure (SAX only)

---

Functions and Methods of Parser APIs

Table 13-2 Summary of Functions and Methods of Parser APIs  

Function / Method	Description
freeElements()	Frees an allocated list of element nodes.
getEncoding()	Returns document's encoding.
isSingleChar()	Determines if document data is single or multibyte.
isStandalone()	Determines if document is standalone.
isUnicode()	Determines if document data is Unicode.
saveString()	Allocates memory and saves the NULL-terminated single or multibyte string in the XML string pool.
saveString2()	Allocates memory and saves the NULL-terminated Unicode string in the XML string pool.
printBuffer()	Prints representation of XML tree into buffer.
printSize()	Returns size of printed representation of XML tree.
printStream()	Writes a printed representation of an XML tree to file stream.
setDocOrder()	Sets the document order for each node in the current document.
xmlaccess()	Sets the I/O callback functions for the given access method.
xmlclean()	Frees any memory used during the previous parse.
xmlinit()	Initializes XML parser.
xmlinitenc()	Initializes XML parser specifying DOM data encoding.
xmlLocation()	Returns current location while parsing.
xmlparse()	Parses a URI.
xmlparsebuf()	Parses a buffer.
xmlparsedtd()	Parses an external DTD.
xmlparsefile()	Parses a file.
xmlparsestream()	Parses a user-defined stream.
xmlterm()	Shuts down XML parser.
xmlwhere()	Returns error location information.

freeElements()

Description

Frees an allocated list of element nodes. Used primarily to free the lists created by getElementsByTagName().

Syntax

void freeElements( xmlctx *ctx,
                   xmlnodes *list);

Parameter	IN / OUT	Description
ctx	(IN)	XML context.
list	(IN)	List of nodes to free

getEncoding()

Description

This function returns the IANA/Mime name of the DOM/SAX data encoding, such as "ASCII", "ISO-8859-1", "UTF-8", "UTF-16", and so on. See also the isSingleChar() function, which can be used to determine if the data is single or multibyte, and the isUnicode() function, which determines if the data is Unicode (UTF-16). The data encoding is specified by the user at initiation time.

Syntax

oratext *getEncoding( xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	The XML parser context.

isSingleChar()

Description

Returns a flag which specifies whether data encoding to this context is singlebyte characters (like ASCII, ISO-8859, EBCDIC, and others), or multibyte characters (like UTF-8 or Unicode). See getEncoding(), which returns the name of the data encoding.

Syntax

boolean isSingleChar( xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	The XML parser context

isStandalone()

Description

Returns value of document's standalone flag. This function returns the boolean value of the document's standalone flag, as specified in the XML declaration.

Syntax

boolean isStandalone( xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	The XML parser context

isUnicode()

Description

Returns the Unicode (UCS2) encoding flag. Similar to a isSingleChar().

Syntax

boolean isUnicode(xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	The XML parser context

saveString()

Description

Allocates memory and saves the NULL-terminated single or multibyte string in the XML string pool. Strings saved this way cannot be freed individually since they are stored head-to-tail in a single pool, for maximum compactness. The memory is reused only when the entire pool is freed, after an xmlclean() or xmlterm() calls. Use saveString2() for saving Unicode strings.

Syntax

oratext *saveString( xmlctx *ctx,
                     oratext *str);

Parameter	IN / OUT	Description
xtx	(IN)	LPX context
str	(IN)	Pointer to a single or multibyte string.

saveString2()

Description

Allocates memory and saves the NULL-terminated Unicode string in the XML string pool. Note that a Unicode string is terminated with TWO NULL bytes, not just one! Strings saved this way cannot be freed individually since they are stored head-to-tail in a single pool, for maximum compactness. The memory is reused only when the entire pool is freed, after an xmlclean() or xmlterm() calls. Use saveString() for saving single or multibyte strings.

Syntax

ub2 *saveString2( xmlctx *ctx,
                  ub2 *ustr);

Parameter	IN / OUT	Description
xtx	(IN)	LPX context
ustr	(IN)	Pointer to a unicode string

printBuffer()

Description

Creates a printed representation of an XML tree rooted at the given node, and puts it into a destination buffer. Indentation is controlled by level and step: step is the number of spaces to indent each new level, and level is the starting level; 0 for top- level.

Syntax

void printBuffer( oratext *buffer,
                  size_t bufsiz,
                  xmlnode *node,
                  uword step,
                  uword level);

Parameter	IN / OUT	Description
buffer	(IN)	destination buffer where output is placed
bufsiz	(IN)	size of destination buffer
node	(IN)	root node of XML tree to print
step	(IN)	number of spaces to indent each new level
level	(IN)	starting level of indentation

printSize()

Description

Returns the size of the printed representation of an XML tree, rooted at the given node. Indentation is controlled by level and step as for printBuffer: step is the number of spaces to indent each new level, and level is the starting level; 0 for top-level. This function is used to pre-compute the size of the buffer needed for printBuffer().

Syntax

size_t printSize( xmlnode *node, 
                  uword step,
                  uword level);

Parameter	IN / OUT	Description
node	(IN)	root node of XML tree to print
step	(IN)	number of spaces to indent each new level
level	(IN)	starting level of indentation

printStream()

Description

Writes a printed representation of an XML tree (rooted at the given node) to a stdio stream (FILE*). This function is exactly like printBuffer except output is to a stream instead of into a buffer. Indentation is controlled by level and step: step is the number of spaces to indent each new level, and level is the starting level (0 for top-level).

Syntax

void printStream( FILE *stream,
                  xmlnode *node,
                  uword step,
                  uword level);

Parameter	IN / OUT	Description
stream	(IN)	output stream to write to
node	(IN)	root node of XML tree to print
step	(IN)	number of spaces to indent each new level
level	(IN)	starting level of indentation

setDocOrder()

Description

Sets the document order for each node in the current document. Must be called once on the final document before XSLT processing can occur. Note this is called automatically by the XSLT processor, so ordinarily the user need not make this call.

Syntax

ub4 setDocOrder(xmlctx *ctx, ub4 start_id);

Parameter	IN / OUT	Description
ctx	(IN)	XML context
start_id	((N)	Initial id number to assign

xmlaccess()

Description

Sets the I/O callback functions for the given access method.

Syntax

uword xmlaccess( xmlctx *ctx,
                 xmlacctype access,
                 XML_OPENF((*openf)),
                 XML_CLOSEF((*closef)),
                 XML_READF((*readf)));

Parameter	IN / OUT	Description
ctx	(IN)	The XML context
access	(IN)	Access method enum, XMLACCESS_xxx
openf	(IN)	Open-input callback function
closef	(IN)	Close-input callback function
readf	(IN)	Read-input callback function

Comments

Sets the I/O callback functions for the given access method. Most methods have built-in callback functions, so do not have to be provided by the user. The notable exception is XMLACCESS_STREAM, where the user must set the stream callback functions themselves.

The three callback functions are invoked to open, close, and read from the input source. The functions should have been declared using the function prototype macros XML_OPENF, XML_CLOSEF and XML_READF.

XML_OPENF is the open function, called once to open the input source. It should set 
its persistent handle in the xmlihdl union, which has two choices, a generic 
pointer (void *), and an integer (as unix file or socket handle). This function 
must return XMLERR_OK on success. 

Parameter	IN / OUT	Description
ctx	(IN)	XML context.
ih	(OUT)	The opened handle is placed here.
length	(OUT)	Total length of input data in bytes, if known (0 if not known).
parts	(IN)	URL broken down into components; opaque pointer.
path	(IN)	Full URL to be opened.

XML_CLOSEF is the close function; it closes an open source and frees resources. 

Parameter	IN / OUT	Description
ctx	(IN)	XML context.
ih	(IN)	The opened handle.

XML_READF is the reader function; it reads data from an open source into a buffer, and returns the number of bytes read:

• If <= 0, an EOI condition is indicated.
• If > 0, then the EOI flag determines if this is the final data.

  On EOI, the matching close function will be called automatically.
  

  Parameter	IN / OUT	Description
  ctx	(IN)	XML context.
  dest	(OUT)	Destination buffer to read data into.
  destsize	(IN)	Size of dest buffer.
  eoi	(OUT)	Hit End of Information?
  ih	(IN)	Input handle union from which to read.
  nraw	(OUT)	Number of bytes read.
  path	(IN)	URL of source provided for use in error messages.

xmlclean()

Description

Recycles memory within the XML parser, but does not free it to the system; only xmlterm() finally releases all memory back to the system. If xmlclean() is not called between parses, then the data used by the previous documents remains allocated, and pointers to it are valid. Thus, the data for multiple documents can be accessible simultaneously, although only the current document can be manipulated with DOM.

If only access to only one document's data at a time within a single context is desired, than clear() should be called before each new parse.

Syntax

void xmlclean( xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	The XML parser context

xmlinit()

Description

Initializes the XML parser. It must be called before any parsing can take place.

• The C version of this call returns the XML context on success, and sets the user's err argument on error. As usual, a zero error code means success, nonzero indicates a problem.
• This function should only be called once before starting the processing of one or more XML files. xmlterm() should be called after all processing of XML files has completed.
• For C, all arguments may be NULL except for err. For C++, all arguments have default values and may be omitted if not needed.
• By default, the data encoding is UTF-8. If documents are singlebyte, encoding should be set accordingly for better performance.
• Messages are printed to stderr unless msghdlr is given.
• By default, a DOM tree is built. For SAX mode, the saxcb callbacks should be set. Note that any of the SAX callback functions may be set to NULL if not needed.
• The memory callback memcb may be used for user-defined memory allocation. Both alloc() and free() functions must be specified.
• The parameters msgctx, saxcbctx, and memcbctx can be used to define and pass information to user-defined callback routines for the message handler, SAX functions, or memory functions, respectively. They should be set to NULL if user-defined callback functions do not need any additional information passed in to them.
• The lang parameter determines the language of error messages; the default is "American."
• Returns the XML context on success; sets the user's err argument on error. A zero error code means success, nonzero indicates a problem.

Syntax

xmlctx *xmlinit( uword *err,
                 const oratext *incoding,
                 XML_MSGHDLRF((*msghdlr)),
                 void *msgctx,
                 const xmlsaxcb *saxcb,
                 void *saxcbctx, 
                 const xmlmemcb *memcb,
                 void *memcbctx,
                 const oratext *lang);

Parameter	IN / OUT	Description
err	(OUT)	Numeric error code, on failure.
incoding	(IN)	Default input encoding.
msghdlr	(IN)	Error message handler function.
msgctx	(IN)	User's context for the error message handler.
saxcb	(IN)	SAX callback structure, filled with function pointers.
saxcbctx	(IN)	User's context for SAX callbacks.
memcb	(IN)	Memory function callback structure.
memcbctx	(IN)	User's context for the memory function callbacks.
lang	(IN)	Language for error messages.

Error Code	Description
XMLERR_BAD_ENCODING	An encoding was not known. Use IANA/Mine names for encodings, and make sure Globalization Support data is present.
XMLERR_INVALID_LANG	The language specified for error messages was not known.
XMLERR_INVALID_MEMCB	A memory callback structure (memcb) was specified, but it did not have alloc and free function pointers.
XMLERR_LEH_INIT	The LEH (catch/throw) package could not be initialized. An internal error, contact support.
XMLERR_NLS_INIT	The National Language Service package could not be initialized. Perhaps an installation or configuration problem.

xmlinitenc()

Description

Initializes the XML parser, specifying DOM data encoding. It must be called before any parsing can take place. Same as SAX xmlinit(), but allows data encoding to be specified.

Syntax

xmlctx *xmlinitenc( uword *err,
                    const oratext *incoding, 
                    const oratext *outcoding,
                    XML_MSGHDLRF((*msghdlr)),
                    void *msgctx,
                    const xmlsaxcb *saxcb,
                    void *saxcbctx, 
                    const xmlmemcb *memcb,
                    void *memcbctx,
                    const oratext *lang);

Parameter	IN / OUT	Description
err	(OUT)	Numeric error code, on failure.
incoding	(IN)	Default input encoding.
outcoding	(IN)	Output (DIM/SAX data) character set encoding.
msghdlr	(IN)	Error message handler function.
msgctx	(IN)	User's context for the error message handler.
saxcb	(IN)	SAX callback structure, filled with function pointers.
saxcbctx	(IN)	User's context for SAX callbacks.
memcb	(IN)	Memory function callback structure.
memcbctx	(IN)	User's context for the memory function callbacks.
lang	(IN)	Language for error messages.

Error Code	Description
XMLERR_BAD_ENCODING	An encoding was not known. Use IANA/Mine names for encodings, and make sure Globalization Support data is present.
XMLERR_INVALID_LANG	The language specified for error messages was not known.
XMLERR_INVALID_MEMCB	A memory callback structure (memcb) was specified, but it did not have alloc and free function pointers.
XMLERR_LEH_INIT	The LEH (catch/throw) package could not be initialized. An internal error, contact support.
XMLERR_NLS_INIT	The National Language Service package could not be initialized. Perhaps an installation or configuration problem.

Parameter	IN / OUT	Description

xmlLocation()

Description

Returns current source location while parsing. This function may be called at any time. However, a 0 will be returned for both path and line if the call is not made during parsing.

Syntax

uword xmlLocation( xmlctx *ctx,
                   ub4 *line,
                   oratext **path);

Parameter	IN / OUT	Description
ctx	(IN)	The XML parser context
line	(OUT)	Current line number
path	(OUT)	Current source path/URL

xmlparse()

Description

Invokes the XML parser on an input document that is specified by a URI. The parser must have been initialized successfully with a call to xmlinit() or xmlinitenc() first. Parser options are specified as flag bits OR'd together into the flags mask.

The default input encoding may be specified as incoding, which overrides the incoding given to xmlinit(). If the input's encoding cannot be determined automatically, based on BOM, XMLDecl, and others, then it is assumed to be incoding. IANA/Mime encoding names should be used, "UTF-8", "ASCII", others.

Syntax

uword xmlparse( xmlctx *ctx,
                const oratext *uri,
                const oratext *incoding,
                ub4 flags);

Parameter	IN / OUT	Description
ctx	(IN/OUT)	The XML parser context
uri	(IN)	URI of XML document
incoding	(IN)	Default input encoding
flags	(IN)	Mask of parser option flag bits

Parser Flag Option	Description
XML_DTD_ONLY	Parses an external subset. This is the same as calling xmlparsedtd(); it parses an external subset (DTD) instead of a complete XML document. Used primarily by the Class Generator so that it may generate classes from a DTD without need of a complete document.
XML_FLAG_DISCARD_WHITESPACE	Discards extraneous whitespace (end-of-line, and so on); default behavior is to report whitespace and indicate which whitespace can be ignored. This option will discard all whitespace between an end-element tag and the following start-element tag.
XML_FLAG_STOP_ON_WARNING	Stops validation on warnings. Validation problems are considered warnings (non-fatal) unless this flag is set. If set, validation will stop after the first warning.
XML_FLAG_VALIDATE	Turns validation on; default behavior is to only check for well-formedness.
XML_FORCE_INCODING	Forces input documents to be interpreted in the encoding "incoding". The default input encoding may be specified as incoding, which overrides the incoding given to xmlinit. If the input's encoding cannot be determined automatically, based on BOM, XMLDecl, and others, then it is assumed to be incoding. IANA/Mime encoding names should be used, "UTF-8", "ASCII", and so on. If XML_FLAG_FORCE_INCODING is set, the document will be interpreted as "incoding" regardless.
XML_WARN_DUPLICATE_ENTITY	Causes a warning to be emitted if a duplicate entity declaration is found. A duplicate entity declaration is usually silently ignored. When set, this flag causes a warning to be emitted instead.

xmlparsebuf()

Description

Invokes the XML parser on a buffer. The parser must have been initialized successfully with a call to xmlinit() or xmlinitenc() first. Parser options are specified as flag bits OR'd together into the flags mask.

The default input encoding may be specified as incoding, which overrides the incoding given to xmlinit(). If the input's encoding cannot be determined automatically, based on BOM, XMLDecl, and others, then it is assumed to be incoding. IANA/Mime encoding names should be used, "UTF-8", "ASCII", others.

Syntax

uword xmlparsebuf( xmlctx *ctx,
                   const oratext *buffer,
                   size_t len,
                   const oratext *incoding,
                   ub4 flags);

Parameter	IN / OUT	Description
ctx	(IN/OUT)	The XML parser context
buffer	(IN)	Input buffer name
len	(IN)	Length of the buffer
incoding	(IN)	Default input encoding
flags	(IN)	Mask of parser option flag bits

Parser Flag Option	Description
XML_DTD_ONLY	Parses an external subset. This is the same as calling xmlparsedtd(); it parses an external subset (DTD) instead of a complete XML document. Used primarily by the Class Generator so that it may generate classes from a DTD without need of a complete document.
XML_FLAG_DISCARD_WHITESPACE	Discards extraneous whitespace (end-of-line, and so on); default behavior is to report whitespace and indicate which whitespace can be ignored. This option will discard all whitespace between an end-element tag and the following start-element tag.
XML_FLAG_STOP_ON_WARNING	Stops validation on warnings. Validation problems are considered warnings (non-fatal) unless this flag is set. If set, validation will stop after the first warning.
XML_FLAG_VALIDATE	Turns validation on; default behavior is to only check for well-formedness.
XML_FORCE_INCODING	Forces input documents to be interpreted in the encoding "incoding". The default input encoding may be specified as incoding, which overrides the incoding given to xmlinit. If the input's encoding cannot be determined automatically, based on BOM, XMLDecl, and others, then it is assumed to be incoding. IANA/Mime encoding names should be used, "UTF-8", "ASCII", and so on. If XML_FLAG_FORCE_INCODING is set, the document will be interpreted as "incoding" regardless.
XML_WARN_DUPLICATE_ENTITY	Causes a warning to be emitted if a duplicate entity declaration is found. A duplicate entity declaration is usually silently ignored. When set, this flag causes a warning to be emitted instead.

xmlparsedtd()

Description

Invokes the XML parser on an external DTD file, not a complete document. It is used mainly by the Class Generator to create classes from a DTD without requiring a complete document. The parser must have been initialized successfully with a call to xmlinit() or xmlinitenc() first. Parser options are specified as flag bits OR'd together into the flags mask.

The default input encoding may be specified as incoding, which overrides the incoding given to xmlinit(). If the input's encoding cannot be determined automatically, based on BOM, XMLDecl, and others, then it is assumed to be incoding. IANA/Mime encoding names should be used, "UTF-8", "ASCII", others.

Syntax

uword xmlparsedtd( xmlctx *ctx,
                   const oratext *filename,
                   oratext *name,
                   const oratext *incoding,
                   ub4 flags);

Parameter	IN / OUT	Description
ctx	(IN/OUT)	The XML parser context
filename	(IN)	File name of the external subset
name	(IN)	Name of the DTD
incoding	(IN)	Default input encoding
flags	(IN)	Mask of parser option flag bits

Parser Flag Option	Description
XML_DTD_ONLY	Parses an external subset. This is the same as calling xmlparsedtd; it parses an external subset (DTD) instead of a complete XML document. Used primarily by the Class Generator so that it may generate classes from a DTD without need of a complete document.
XML_FLAG_DISCARD_WHITESPACE	Discards extraneous whitespace (end-of-line, and so on); default behavior is to report whitespace and indicate which whitespace can be ignored. This option will discard all whitespace between an end-element tag and the following start-element tag.
XML_FLAG_STOP_ON_WARNING	Stops validation on warnings. Validation problems are considered warnings (non-fatal) unless this flag is set. If set, validation will stop after the first warning.
XML_FLAG_VALIDATE	Turns validation on; default behavior is to only check for well-formedness.
XML_FORCE_INCODING	Forces input documents to be interpreted in the encoding "incoding". The default input encoding may be specified as incoding, which overrides the incoding given to xmlinit. If the input's encoding cannot be determined automatically, based on BOM, XMLDecl,and others, then it is assumed to be incoding. IANA/Mime encoding names should be used, "UTF-8", "ASCII", and so on. If XML_FLAG_FORCE_INCODING is set, the document will be interpreted as "incoding" regardless.
XML_WARN_DUPLICATE_ENTITY	Causes a warning to be emitted if a duplicate entity declaration is found. A duplicate entity declaration is usually silently ignored. When set, this flag causes a warning to be emitted instead.

xmlparsefile()

Description

Invokes the XML parser on a document in the file system. The parser must have been initialized successfully with a call to xmlinit() or xmlinitenc() first. Parser options are specified as flag bits OR'd together into the flags mask.

The default input encoding may be specified as incoding, which overrides the incoding given to xmlinit(). If the input's encoding cannot be determined automatically, based on BOM, XMLDecl, and others, then it is assumed to be incoding. IANA/Mime encoding names should be used, "UTF-8", "ASCII", others.

Syntax

uword xmlparsefile( xmlctx *ctx,
                    const oratext *path,
                    const oratext *incoding,
                    ub4 flags);

Parameter	IN / OUT	Description
ctx	(IN/OUT)	The XML parser context
path	(IN)	Filesystem path of the document
incoding	(IN)	Default input encoding
flags	(IN)	Mask of parser option flag bits

Parser Flag Option	Description
XML_DTD_ONLY	Parses an external subset. This is the same as calling xmlparsedtd; it parses an external subset (DTD) instead of a complete XML document. Used primarily by the Class Generator so that it may generate classes from a DTD without need of a complete document.
XML_FLAG_DISCARD_WHITESPACE	Discards extraneous whitespace (end-of-line, and so on); default behavior is to report whitespace and indicate which whitespace can be ignored. This option will discard all whitespace between an end-element tag and the following start-element tag.
XML_FLAG_STOP_ON_WARNING	Stops validation on warnings. Validation problems are considered warnings (non-fatal) unless this flag is set. If set, validation will stop after the first warning.
XML_FLAG_VALIDATE	Turns validation on; default behavior is to only check for well-formedness.
XML_FORCE_INCODING	Forces input documents to be interpreted in the encoding "incoding". The default input encoding may be specified as incoding, which overrides the incoding given to xmlinit. If the input's encoding cannot be determined automatically, based on BOM, XMLDecl,and others, then it is assumed to be incoding. IANA/Mime encoding names should be used, "UTF-8", "ASCII", and so on. If XML_FLAG_FORCE_INCODING is set, the document will be interpreted as "incoding" regardless.
XML_WARN_DUPLICATE_ENTITY	Causes a warning to be emitted if a duplicate entity declaration is found. A duplicate entity declaration is usually silently ignored. When set, this flag causes a warning to be emitted instead.

xmlparsestream()

Description

Invokes the XML parser on a user-defined stream. The parser must have been initialized successfully with a call to xmlinit() or xmlinitenc() first. Parser options are specified as flag bits OR'd together into the flags mask to override the default behavior of the parser.

The default input encoding may be specified as incoding, which overrides the incoding given to xmlinit(). If the input's encoding cannot be determined automatically, based on BOM, XMLDecl, and others, then it is assumed to be incoding. IANA/Mime encoding names should be used, "UTF-8", "ASCII", others.

In the context of this function, a stream is a user defined entity; stream is a stream/context pointer, which is in turn passed to the I/O callback functions. The parser does not reference the stream directly. The I/O callback functions for access method XMLACCESS_STREAM must be set up first. The stream or stream context pointer will be available in each callback function as the ptr_xmlihdl memory of the ihdl structure. Its meaning and use are user-defined.

Syntax

uword xmlparsestream( xmlctx *ctx,
                      const oratext *stream,
                      const oratext *incoding,
                      ub4 flags);

Parameter	IN / OUT	Description
ctx	(IN/OUT)	The XML parser context
stream	(IN)	Pointer to a user-defined stream object
incoding	(IN)	Default input encoding
flags	(IN)	Mask of parser option flag bits

Parser Flag Option	Description
XML_DTD_ONLY	Parses an external subset. This is the same as calling xmlparsedtd; it parses an external subset (DTD) instead of a complete XML document. Used primarily by the Class Generator so that it may generate classes from a DTD without need of a complete document.
XML_FLAG_DISCARD_WHITESPACE	Discards extraneous whitespace (end-of-line, and so on); default behavior is to report whitespace and indicate which whitespace can be ignored. This option will discard all whitespace between an end-element tag and the following start-element tag.
XML_FLAG_STOP_ON_WARNING	Stops validation on warnings. Validation problems are considered warnings (non-fatal) unless this flag is set. If set, validation will stop after the first warning.
XML_FLAG_VALIDATE	Turns validation on; default behavior is to only check for well-formedness.
XML_FORCE_INCODING	Forces input documents to be interpreted in the encoding "incoding". The default input encoding may be specified as incoding, which overrides the incoding given to xmlinit. If the input's encoding cannot be determined automatically, based on BOM, XMLDecl,and others, then it is assumed to be incoding. IANA/Mime encoding names should be used, "UTF-8", "ASCII", and so on. If XML_FLAG_FORCE_INCODING is set, the document will be interpreted as "incoding" regardless.
XML_WARN_DUPLICATE_ENTITY	Causes a warning to be emitted if a duplicate entity declaration is found. A duplicate entity declaration is usually silently ignored. When set, this flag causes a warning to be emitted instead.

xmlterm()

Description

Terminates the XML parser. It should be called after xmlinit, and before exiting the main program.

Syntax

uword xmlterm(xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN/OUT)	The XML parser context

Comments

This function terminates an XML context. All memory used by the parser is returned to the system. The context may not be reused; instead, a new context must be created if additional parsing is to be done. No additional XML parser calls can be made until xmlinit is called again to get a new context. Compare to xmlclean(), which recycles memory internally without giving it back to the system, and allows the context to continue to be used.

xmlwhere()

Description

Returns error location information for the last, or current, error. Returns source location where the current error occurred. Should be called from within an error handler. The source location is a stack. Index 0 is the lowest level where the problem actually occurred, index 1 is the enclosing entity, and so on. To show the whole stack, the index should be looped form 0 to N, stopping when FALSE is returned.

Syntax

boolean xmlwhere( xmlctx *ctx,
                  ub4 *line,
                  oratext **path,
                  unword idx);

Parameter	IN / OUT	Description
ctx	(IN)	The XML parser context
line	(OUT)	Line number where the error occurred
path	(OUT)	Source path/URL where the error occurred
idx	(IN)	Error number in stack, starting at 0

---

W3C SAX APIs

---

Description of W3C SAX APIs

SAX is a standard interface for event-based XML parsing, developed cooperatively by the members of the XML-DEV mailing list.

To use SAX, an xmlsaxcb structure is initialized with function pointers and passed to the xmlinit call. A pointer to a user-defined context structure may also be included; that context pointer will be passed to each SAX function.

---

Callback Structure of W3C SAX APIs

typedef struct
{
   sword (*startDocument)(void *ctx);
   sword (*endDocument)(void *ctx);
   sword (*startElement)(void *ctx, const oratext *name, 
                         const struct xmlnodes *attrs);
   sword (*endElement)(void *ctx, const oratext *name);
   sword (*characters)(void *ctx, const oratext *ch, size_t len);
   sword (*ignorableWhitespace)(void *ctx, const oratext *ch, 
                         size_t len);
   sword (*processingInstruction)(void *ctx, const oratext *target
                         const oratext *data);
   sword (*notationDecl)(void *ctx, const oratext *name,
                         const oratext *publicId, 
                         const oratext *systemId);
   sword (*unparsedEntityDecl)(void *ctx, const oratext *name, 
                         const oratext *publicId,
                         const oratext *systemId, 
                         const oratext *notationName);
   sword (*nsStartElement)(void *ctx, const oratext *qname,
                         const oratext *local, const oratext *nsp,
                         const struct xmlnodes *attrs);
   sword (*comment)(void *ctx, const oratext *data);
   sword (*elementDecl)(void *ctx, const oratext *name,
                         const oratext *content);
   sword (*attributeDecl)(void *ctx, const oratext *elem,
                         const oratext *attr, const oratext *body);
   sword (*xmlDecl)(void *ctx, const oratext *version, boolean encoding);
} xmlsaxcb;

---

Data Structures of W3C SAX APIs

Table 13-3 Data Structures Namespace APIs

Data Stricture	Declaration	Description
oratext*	typedef unsigned char oratext;	Pointer to data; any encoding, including Unicode; cast as needed
sword	typedef signed int sword;	Return value for user SAX callback functions; 0 means success.
xmlnodes*	typedef struct xmlnodes xmlnodes;	Pointer to list of nodes (attributes of an element). Note: xmlnodes* is an opaque type and cannot be referenced directly. Instead, use DOM function getAttributeIndex()

---

Callback Functions

Table 13-4 Summary of SAX Callback Functions  

Function	Description
characters()	Receives notification of character data inside an element.
endDocument()	Receives notification of the end of the document.
endElement()	Receives notification of the end of an element.
ignorableWhitespace()	Receives notification of ignorable whitespace in content.
notationDecl()	Receives notification of a notation declaration.
processingInstruction()	Receives notification of a processing instruction.
startDocument()	Receives notification of the beginning of the document.
startElement()	Receives notification of the start of an element.
unparsedEntityDecl()	Receives notification of an unparsed entity declaration.

Table 13-5 Summary of Oracle SAX Extension Callback Functions

Function	Description
attributeDecl()	Receive notification about an element attribute declaration in the DTD
comment()	Receive notification about a comment in the XML document
elementDecl()	Receive notification about an element declaration in the DTD
ignorableWhitespace()	Receive notification of the start of a namespace for an element.

characters()

Description

Receives notification of character data inside an element.

Syntax

sword (*characters)( void *ctx,
                     const oratext *ch,
                     size_t len);

Parameter	IN / OUT	Description
ctx	(IN)	User's context
ch	(IN)	Pointer to character data
len	(IN)	Length of data in characters

endDocument()

Description

Receives notification of the end of the document.

Syntax

sword (*endDocument) void *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	client context

endElement()

Description

Receives notification of the end of an element.

Syntax

sword (*endElement)( void *ctx,
                     const oratext *name);

Parameter	IN / OUT	Description
ctx	(IN)	client context
name	(IN)	element type name

ignorableWhitespace()

Description

Receives notification of ignorable whitespace in element content.

Syntax

sword (*ignorableWhitespace)( void *ctx,
                              const oratext *ch,
                              size_t len);

Parameter	IN / OUT	Description
ctx	(IN)	User's context
ch	(IN)	Pointer to character data
len	(IN)	Length of data in characters

notationDecl()

Description

Receives notification of a notation declaration.

Syntax

sword (*notationDecl)( void *ctx,
                       const oratext *name, 
                       const oratext *publicId,
                       const oratext *systemId);

Parameter	IN / OUT	Description
ctx	(IN)	User's context
name	(IN)	Notation name
publicID	(IN)	Notation public identifier, NULL if not available
systemId	(IN)	Notation system identifier

processingInstruction()

Description

Receives notification of a processing instruction.

Syntax

sword (*processingInstruction)( void *ctx,
                                const oratext *target, 
                                const oratext *data);

Parameter	IN / OUT	Description
ctx	(IN)	User's context
target	(IN)	Processing instruction target
data	(IN)	Processing instruction data; NULL if no data is supplied

startDocument()

Description

Receives notification of the beginning of the document.

Syntax

sword (*startDocument)( void *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	User's context

startElement()

Description

Receives non-namespace-aware notification of the beginning of an element.

Syntax

sword (*startElement)( void *ctx,
                       const oratext *name,
                       const struct xmlnodes *attrs);

Parameter	IN / OUT	Description
ctx	(IN)	User's context
name	(IN)	Element name
attrs	(IN)	Specified or defaulted attributes

unparsedEntityDecl()

Description

Receives notification of an unparsed entity declaration.

Syntax

sword (*unparsedEntityDecl)( void *ctx, 
                             const oratext *name, 
                             const oratext *publicId,
                             const oratext *systemId, 
                             const oratext *notationName);

Parameter	IN / OUT	Description
ctx	(IN)	User's context
name	(IN)	Entity name
publicId	(IN)	Entity public identifier, NULL if not available
systemId	(IN)	Entity system identifier
notationName	(IN)	Name of the associated notation

attributeDecl()

Description

Receives notification about an element's attribute declaration.

Syntax

sword (*attributeDecl)( void *ctx,
                        const oratext *elem,
                        const oratext *attr,
                        const oratext *body);

Parameter	IN / OUT	Description
ctx	(IN)	User's context
elem	(N)	Element name
attr	(IN)	Attribute name
body	(IN)	Body of attribute declaration

comment()

Description

Receives notification about a comment.

Syntax

sword (*comment)( void *ctx,
                  const oratext *data);

Parameter	IN / OUT	Description
ctx	(IN)	client context
data	(IN)	body of comment

elementDecl()

Description

Receives notification about an element declaration.

Syntax

sword (*elementDecl)( void *ctx,
                      const oratext *name, 
                      const oratext *content);

Parameter	IN / OUT	Description
ctx	(IN)	User's context
name	(IN)	Element name
content	(IN)	Element content model

nsStartElement()

Description

Receives namespace-aware notification of the start of an element.

Syntax

sword (*nsStartElement)( void *ctx,
                         const oratext *qname, 
                         const oratext *local,
                         const oratext *namespace,
                         const struct xmlnodes *attrs);

Parameter	IN / OUT	Description
ctx	(IN)	client context
qname	(IN)	element fully qualified name
local	(IN)	element local name
namespace	(IN)	element namespace (URI)
attrs	(IN)	specified or defaulted attributes

---

W3C DOM APIs

---

Description of W3C DOM APIs

Since the DOM standard is object-oriented, the following changes were made for the C adaptation:

• Reused function names were expanded; for example, getValue() in the attribute class was given the unique name getAttrValue(), matching the pattern established by getNodeValue().
• Some functions were added to extend the DOM; for example, there is no function defined that returns the number of children of a node, so numChildNodes() was added.

The implementation of this C DOM interface follows REC-DOM-Level-1-19981001.

---

Data Structures of W3C DOM APIs

Table 13-6 Data Structures of W3C DOM APIs  

Data Structure	Declaration	Description
boolean	typedef int boolean;	Boolean value, TRUE or FALSE
oratext	typedef unsigned char oratext;	String pointer
xmlctx	typedef struct xmlctx xmlctx;	Master XML parser context. Note: The contents of xmlctx are private and must not be accessed by users.
xmlnode	typedef struct xmlnode xmlnode;	Document node. Note: The contents of xmlnode are private and must not be accessed by users.
xmlnodes	typedef struct xmlnodes xmlnodes;	Array of nodes. Note: The contents of xmlnodes are private and must not be accessed by users.
xmlntype	ELEMENT_NODE = 1 /* element */ ATTRIBUTE_NODE = 2 /* attribute */ TEXT_NODE = 3 /* char data not escaped by CDATA */ CDATA_SECTION_NODE = 4 /* char data escaped by CDATA */ ENTITY_REFERENCE_NODE = 5 /* entity reference */ ENTITY_NODE = 6 /* entity */ PROCESSING_INSTRUCTION_NODE = 7 /* processing instruction */ COMMENT_NODE= 8 /* comment */ DOCUMENT_NODE = /* document */ DOCUMENT_TYPE_NODE = 10 /* DTD */ DOCUMENT_FRAGMENT_NODE = 11 /* document fragment */ NOTATION_NODE = 12 /* notation */	Node type enumeration Note: Names and values match DOM specification. Parse tree node types; see getNodeType().

---

Functions of W3C DOM APIs

Table 13-7 Summary of Functions of W3C DOM APIs  

Function	Description
appendChild()	Appends child node to the parent's list of children.
appendData()	Appends character data to the node's current data.
cloneNode()	Creates a new node identical to the given node.
createAttribute()	Creates a non-namespace aware attribute for an element node.
createAttributeNS()	Creates a namespace-aware attribute for an element node.
createCDATASection()	Creates a CDATA_SECTION node.
createComment()	Creates a COMMENT node.
createDocument()	Creates a non-namespace-aware DOCUMENT node
createDocumentFragment()	Creates a DOCUMENT_FRAGMENT node.
createDocumentNS()	Creates a namespace-aware DOCUMENT node.
createDocumentType()	Creates a new DTD node.
createElement()	Creates a non-namespace-aware ELEMENT node.
createElementNS()	Creates a namespace-aware ELEMENT node.
createEntityReference()	Creates an ENTITY_REFERENCE node.
createProcessingInstruction()	Creates a PROCESSING_INSTRUCTION (PI) node.
createTextNode()	Creates a TEXT node.
deleteData()	Removes substring from a node's character data.
getAttribute()	Returns one attribute from an array, given its index.
getAttributeIndex()	Returns an element's attribute given its index.
getAttrName()	Returns an attribute's name.
getAttributeNode()	Returns an element's attribute node given its name.
getAttributes()	Returns an array of element's attributes.
getAttrSpecified()	Returns value of attribute's specified flag.
getAttrValue()	Returns the value of an attribute
getCharData()	Returns character data for a TEXT node.
getCharLength()	Returns length of TEXT node's character data.
getChildNode()	Returns node from array of nodes, given the child's index.
getChildNodes()	Returns array of node's children.
getContentModel()	Returns the content model for an element from the DTD.
getDocOrder()	Returns a document order cardinal for a node.
getDocType()	Returns current DTD.
getDocTypeEntities()	Returns a list of a DTD's general entities.
getDocTypeName()	Returns name of DTD.
getDocTypeNotations()	Returns a list of DTD's notations.
getDocument()	Returns top-level DOCUMENT node.
getDocumentElement()	Returns highest-level, or root, ELEMENT node.
getElementByID()	Returns the element node which has the given ID.
getElementsByTagName()	Returns list of elements with matching name.
getElementsByTagNameNS()	Returns list of elements with matching name with namespace information.
getEntityNotation()	Returns an entity's NDATA.
getEntityPubID()	Returns an entity's public ID.
getEntitySysID()	Returns an entity's system ID.
getFirstChild()	Returns the first child of a node
getImplementation()	Returns DOM-implementation structure.
getLastChild()	Returns the last child of a node.
getNamedItem()	Returns the named node from a list of nodes.
getNextSibling()	Returns a node's next sibling.
getNodeMapLength()	Returns number of entries in a NodeMap [DOM getLength]
getNodeName()	Returns a node's name
getNodeType()	Returns a node's type code (enumeration)
getNodeValue()	Returns a node's "value", its character data
getNotationPubID()	Returns a notation's public ID [DOM getPublicId]
getNotationSysID()	Returns a notation's system ID [DOM getSystemId]
getOwnerDocument()	Returns the DOCUMENT node containing the given node
getParentNode()	Returns a node's parent node
getPIData()	Returns a processing instruction's data [DOM getData]
getPITarget()	Returns a processing instruction's target [DOM getTarget]
getPreviousSibling()	Returns a node's "previous" sibling
getTagName()	Returns a node's "tagname", same as name for now
hasAttributes()	Determine if element node has attributes [DOM extension]
hasChildNodes()	Determine if node has children
hasFeature()	Determine if DOM implementation supports a specific feature
importNode()	Copy a node from a different document into this document
insertBefore()	Inserts a new child node before the given reference node
insertData()	Inserts new character data into a node's existing data
isStandalone()	Determine if document is standalone [DOM extension]
nodeValid()	Validate a node against the current DTD [DOM extension]
normalize()	Normalize a node by merging adjacent TEXT nodes
numAttributes()	Returns number of element node's attributes [DOM extension]
numChildNodes()	Returns number of node's children [DOM extension]
prefixToURI()	Returns a matching URI, given a namespace prefix and a node.
removeAttribute()	Removes an element's attribute given its names
removeAttributeNode()	Removes an element's attribute given its pointer
removeChild()	Removes a node from its parents list of children
removeNamedItem()	Removes a node from a list of nodes given its name
replaceChild()	Replace one node with another
replaceData()	Replace a substring of a node's character data with another string
saveString()	Saves a character string in the XML memory pool
saveString2()
setAttribute()	Sets (adds or replaces) a new attribute for an element node given the attribute's name and value
setAttributeNode()	Sets (adds or replaces) a new attribute for an element node given a pointer to the new attribute
setAttrValue()	Sets an attribute's value
setCharData()	Sets a TEXT or CDATA node's value
setNamedItem()	Sets (adds or replaces) a new node in a parent's list of children
setNodeValue()	Sets a node's "value" (character data)
setPIData()	Sets a processing instruction's data [DOM setData]
splitText()	Split a node's character data into two parts
substringData()	Return a substring of a node's character data

appendChild()

Description

Adds new node to the end of the list of children for the given parent and returns the node added.

Syntax

xmlnode *appendChild( xmlctx *ctx,
                      xmlnode *parent,
                      xmlnode *newnode);

Parameter	IN / OUT	Description
ctx	(IN)	xml context
parent	(IN)	parent node
newnode	(IN)	new node to append

appendData()

Description

Append the given string to the character data of a TEXT or CDATA node.

Syntax

void appendData( xmlctx *ctx,
                 xmlnode *node,
                 const oratext *arg);

Parameter	IN / OUT	Description
ctx	(IN)	xml context
node	(IN)	pointer to node
arg	(IN)	new data to append

cloneNode()

Description

Returns a duplicate of this node; serves as a generic copy constructor for nodes. The duplicate node has no parent, therefore parentNode() returns NULL. Cloning an Element copies all attributes and their values, including those generated by the XML processor to represent defaulted attributes, but this method does not copy any text it contains unless it is a deep clone, since the text is contained in a child Text node. Cloning any other type of node simply returns a copy of this node. A deep clone is different in that the node's children are also recursively cloned, instead of just being pointed to.

Syntax

xmlnode *cloneNode( xmlctx *ctx,
                    const xmlnode *old,
                    boolean deep);

Parameter	IN / OUT	Description
ctx	(IN)	xml context
old	(IN)	old node to clone
deep	(IN)	recursion flag

createAttribute()

Description

Creates a new ATTRIBUTE node with the given name and value. The new node is unattached and must be added to an element node with setAttributeNode().

Syntax

xmlnode *createAttribute( xmlctx *ctx,
                          const oratext *name, 
                          const oratext *value);

Parameter	IN / OUT	Description
ctx	(IN)	xml context
name	(IN)	name of new attribute
value	(IN)	value of new attribute

createAttributeNS()

Description

Creates a new ATTRIBUTE node with the given name and value with namespace information. The new node is unattached and must be added to an element node with setAttributeNode().

Syntax

xmlnode *createAttributeNS( xmlctx *ctx,
                            const oratext *uri, 
                            const oratext *qname,
                            const oratext *value);

Parameter	IN / OUT	Description
ctx	(IN)	xml context
uri	(IN)	namespace URI of new attribute
qname	(IN)	qualified name of new attribute
value	(IN)	value of new attribute

createCDATASection()

Description

Creates a new CDATA node.

Syntax

xmlnode *createCDATASection( xmlctx *ctx,
                             const oratext *data);

Parameter	IN / OUT	Description
ctx	(IN)	xml context
data	(IN)	CDATA body

createComment()

Description

Creates a new COMMENT node.

Syntax

xmlnode *createComment( xmlctx *ctx,
                        const oratext *data);

Parameter	IN / OUT	Description
ctx	(IN)	xml context
data	(IN)	text of comment

createDocument()

Description

Creates a new document in memory. The original function createDocument() has now been standardized in DOM 2.0 CORE. For compatibility, the old function remains with its original usage, and the new CORE function is called createDocumentNS(). An XML document is always rooted in a node of type DOCUMENT_NODE; this function creates that root node and sets it in the context. There can be only one current document and hence only one document node; if one already exists, this function does nothing and returns NULL.

Syntax

xmlnode* createDocument( xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	XML parser context

createDocumentFragment()

Description

Creates a new DOCUMENT_FRAGMENT node. A document fragment is a lightweight document object that contains one or more children, but does not have the overhead of a full document. It can be used in some operations (inserting for example) in place of a simple node, in which case all the fragment's children are operated on instead of the fragment node itself.

Syntax

xmlnode *createDocumentFragment( xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	xml context

createDocumentNS()

Description

Creates a new document in memory. The original function createDocument() has now been standardized in DOM 2.0 CORE. For compatibility, the old function remains with its original usage, and the new CORE function is called createDocumentNS. Creates a new document in memory. An XML document is always rooted in a node of type DOCUMENT_NODE-- this function creates that root node and sets it in the context. There can be only one current document and hence only one document node; if one already exists, this function does nothing and returns NULL. If a DTD is specified, its ownerDocument() attribute will be set to the document being created.

Syntax

xmlnode* createDocumentNS( xmldomimp *imp,
                           oratext *uri,
                           oratext *qname,
                           xmlnode *dtd);

Parameter	IN / OUT	Description
imp	(IN)	XML DOMImplementation, see getImplementation()
uri	(IN)	new document's namespace URI
qname	(IN)	namespace qualified name of new document; DOCUMENT_NODE's name
dtd	(IN)	DTD with which this document is associated

createDocumentType()

Description

Creates a new document type (DTD) node.

Syntax

xmlnode* createDocumentType( xmldomimp *imp,
                     oratext *qname,
                     oratext *pubid,
                     oratext *sysid);

Parameter	IN / OUT	Description
imp	(IN)	The XML DOM implementation; see getImplementation().
pubid	(IN)	External subset public identifier
qname	(IN)	The namespace qualified name of a new document type; DOCUMENT_NODE's name
sysid	(IN)	External subset system identifier

createElement()

Description

Create a new ELEMENT node.

Syntax

xmlnode *createElement( xmlctx *ctx,
                        const oratext *elname);

Parameter	IN / OUT	Description
ctx	(IN)	xml context
elname	(IN)	name of new element

createElementNS()

Description

Creates a new ELEMENT node with namespace information.

Syntax

xmlnode *createElementNS( xmlctx *ctx,
                          const oratext *uri, 
                          const oratext *qname);

Parameter	IN / OUT	Description
ctx	(IN)	xml context
uri	(IN)	namespace URI of new element
qname	(IN)	qualified name of new element

createEntityReference()

Description

Creates a new ENTITY_REFERENCE node.

Syntax

xmlnode *createEntityReference( xmlctx *ctx,
                                const oratext *name);

Parameter	IN / OUT	Description
ctx	(IN)	xml context
name	(IN)	name of entity to reference

createProcessingInstruction()

Description

Creates a new PROCESSING_INSTRUCTION node with the given target and 
contents.

Syntax

xmlnode *createProcessingInstruction( xmlctx *ctx,
                                      const oratext *target,
                                      const oratext *data);

Parameter	IN / OUT	Description
ctx	(IN)	xml context
target	(IN)	PI target
data	(IN)	PI definition

createTextNode()

Description

Create a new TEXT node with the given contents.

Syntax

xmlnode *createTextNode( xmlctx *ctx,
                         const oratext *data);

Parameter	IN / OUT	Description
ctx	(IN)	xml context
data	(IN)	data for node

deleteData()

Description

Deletes a substring from the node's character data.

Syntax

void deleteData( xmlctx *ctx,
                 xmlnode *node,
                 ub4 offset,
                 ub4 count);

Parameter	IN / OUT	Description
ctx	(IN)	xml context
node	(IN)	pointer to node
offset	(IN)	offset of start of substring; 0 is first char
count	(IN)	length of substring

getAttribute()

Description

Returns one attribute from an array of attributes, given an index (starting at 0). Fetch the attribute name or value, or both, with getAttrName() and getAttrValue(). On error, returns NULL.

Syntax

const oratext *getAttribute( const xmlnode *node,
                             const oratext *name);

Parameter	IN / OUT	Description
node	(IN)	pointer to node
name	(IN)	name of attribute

getAttributeIndex()

Description

Returns one attribute from an array of attributes, given an index (starting at 0). Fetches the attribute name or value, or both, with getAttrName() and getAttrValue(). On error, returns NULL.

Syntax

xmlnode *getAttributeIndex( const xmlnodes *attrs,
                            size_t index);

Parameter	IN / OUT	Description
attrs	(IN)	pointer to attribute nodes structure, as returned by getAttribute()
index	(IN)	zero-based attribute number returned

getAttrName()

Description

Returns the name of the attribute given a pointer to that attribute. Under the DOM spec, this is a method named getName().

Syntax

const oratext *getAttrName( const xmlnode *attr);

Parameter	IN / OUT	Description
attr	(IN)	pointer to attribute; see getAttribute()

getAttributeNode()

Description

Returns a pointer to the element node's attribute of the given name. If no such thing exists, returns NULL.

Syntax

xmlnode *getAttributeNode( const xmlnode *elem,
                           const oratext *name);

Parameter	IN / OUT	Description
elem	(IN)	pointer to element node
name	(IN)	name of attribute

getAttributes()

Description

Returns an array of all attributes of the given node. This pointer may then be passed to getAttribute to fetch individual attribute pointers, or to numAttributes to return the total number of attributes. If no attributes are defined, returns NULL.

Syntax

xmlnodes *getAttributes( const xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	node whose attributes to return

getAttrSpecified()

Description

Returns the 'specified' flag for the attribute: if this attribute was explicitly given a value in the original document or through the DOM, this is TRUE; otherwise, it is FALSE. If the node is not an attribute, returns FALSE. Under the DOM spec, this is a method named getSpecified().

Syntax

boolean getAttrSpecified( const xmlnode *attr);

Parameter	IN / OUT	Description
attr	(IN)	pointer to attribute; see getAttribute()

getAttrValue()

Description

Given a pointer to an attribute, returns the "value" (definition) of the attribute. Under the DOM spec, this is a method named getValue().

Syntax

const oratext *getAttrValue( const xmlnode *attr);

Parameter	IN / OUT	Description
attr	(IN)	pointer to attribute; see getAttribute()

getCharData()

Description

Returns the character data of a TEXT or CDATA node. Under the DOM spec, this is a method named getData().

Syntax

const oratext *getCharData( const xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	pointer to text node

getCharLength()

Description

Returns the length of the character data of a TEXT or CDATA node. Under the DOM spec, this is a method named getLength().

Syntax

ub4 getCharLength( const xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	pointer to text node

getChildNode()

Description

Returns the nth node in an array of nodes, or NULL if the numbered node does not exist. Invented function, not in DOM, but named to match the DOM pattern.

Syntax

xmlnode* getChildNode( const xmlnodes *nodes,
                       size_t index);

Parameter	IN / OUT	Description
nodes	(IN)	array of nodes; see getChildNodes()
index	(IN)	zero-based child number

getChildNodes()

Description

Returns the array of children of the given node. This pointer may then be passed to getChildNode() to fetch individual children.

Syntax

xmlnodes* getChildNodes( const xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	node whose children to return

getContentModel()

Description

Returns the content model for the named element from the current DTD. The content model is composed of xmlnodes, so may be traversed with the same functions as the parsed document.

Syntax

xmlnode *getContentModel( xmldtd *dtd,
                          oratext *name);

Parameter	IN / OUT	Description
dtd	(IN)	pointer to the DTD
name	(IN)	name of element

getDocOrder()

Description

Returns the document order cardinal for a node. setDocOrder() must have been called first or all nodes will have a 0 order. This function is used primarily by the XSLT processor.

Syntax

ub4 getDocOrder( xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	Node whose doc order to return.

getDocType()

Description

Returns a pointer to the (opaque) DTD for the current document.

Syntax

xmldtd* getDocType( xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	XML parser content

getDocTypeEntities()

Description

Returns an array of (general) entities defined for the given DTD.

Syntax

xmlnodes *getDocTypeEntities( xmldtd* dtd);

Parameter	IN / OUT	Description
dtd	(IN)	pointer to the DTD

getDocTypeName()

Description

Returns the given DTD's name.

Syntax

oratext *getDocTypeName( xmldtd* dtd);

Parameter	IN / OUT	Description
dtd	(IN)	pointer to the DTD

getDocTypeNotations()

Description

Returns an array of notations defined for the given DTD.

Syntax

xmlnodes *getDocTypeNotations( xmldtd* dtd);

Parameter	IN / OUT	Description
dtd	(IN)	pointer to the DTD

getDocument()

Description

Returns the root node of the parsed document. The root node is always of type DOCUMENT_NODE. Compare to the getDocumentElement() function, which returns the root element node, which is a child of the DOCUMENT node.

Syntax

xmlnode* getDocument( xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	XML parser context

getDocumentElement()

Description

Returns the root element (node) of the parsed document. The entire document is rooted at this node. Compare to getDocument which returns the uppermost DOCUMENT node (the parent of the root element node).

Syntax

xmlnode* getDocumentElement( xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	XML parser context

getElementByID()

Description

Returns the element node which has the given ID. If no such ID is defined (or other problems), returns NULL.

Syntax

xmlnode *getElementByID( xmlctx *ctx,
                         oratext *id);

Parameter	IN / OUT	Description
ctx	(IN)	XML parser context
id	(IN)	element id

getElementsByTagName()

Description

Returns a list of all elements (within the tree rooted at the given node) with a given tag name in the order in which they would be encountered in a pre-order traversal of the tree. If root is NULL, the entire document is searched. The special value "*" matches all tags.

Syntax

xmlnodes *getElementsByTagName( xmlctx *ctx,
                                xmlnode *root, 
                                const oratext *name);

Parameter	IN / OUT	Description
ctx	(IN)	XML parser context
root	(IN)	root node of tree
name	(IN)	element tag name

getElementsByTagNameNS()

Description

Returns a list of all elements (within the tree rooted at the given node) with a given tag name in the order in which they would be encountered in a pre-order traversal of the tree. If root is NULL, the entire document is searched. The special value "*" matches all tags.

Syntax

xmlnodes *getElementsByTagNameNS( xmlctx *ctx,
                                  xmlnode *root, 
                                  const oratext *uri, 
                                  const oratext *local);

Parameter	IN / OUT	Description
ctx	(IN)	XML parser context
root	(IN)	root node of tree
uri	(IN)	element namespace uri
local	(IN)	element local name

getEntityNotation()

Description

Returns an entity node's NDATA (notation). Under the DOM spec, this is a method named getNotationName().

Syntax

const oratext *getEntityNotation( const xmlnode *ent);

Parameter	IN / OUT	Description
ent	(IN)	pointer to entity

getEntityPubID()

Description

Returns an entity node's public ID. Under the DOM spec, this is a method named getPublicId().

Syntax

const oratext *getEntityPubID( const xmlnode *ent);

Parameter	IN / OUT	Description
ent	(IN)	pointer to entity

getEntitySysID()

Description

Returns an entity node's system ID. Under the DOM spec, this is a method named getSystemId().

Syntax

const oratext *getEntitySysID( const xmlnode *ent);

Parameter	IN / OUT	Description
ent	(IN)	pointer to entity

getFirstChild()

Description

Returns the first child of the given node, or NULL if the node has no children.

Syntax

xmlnode* getFirstChild( const xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	pointer to node

getImplementation()

Description

Returns a pointer to the DOMImplementation structure for this implementation, or NULL if no such information is available.

Syntax

xmldomimp* getImplementation xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	XML context

getLastChild()

Description

Returns the last child of the given node, or NULL if the node has no children.

Syntax

xmlnode* getLastChild( const xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	pointer to node

getNamedItem()

Description

Returns the named node from an array nodes; sets the user's index (if provided) to the child# of the node (first node is zero).

Syntax

xmlnode *getNamedItem( const xmlnodes *nodes,
                       const oratext *name,
                       size_t *index);

Parameter	IN / OUT	Description
nodes	(IN)	array of nodes
name	(IN)	name of node to fetch
index	(OUT)	index of found node
nodes	(IN)	array of nodes

getNextSibling()

Description

This function returns a pointer to the next sibling of the given node, that is, the next child of the parent. For the last child, NULL is returned.

Syntax

xmlnode* getNextSibling( const xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	pointer to node

getNodeMapLength()

Description

Returns the number of nodes in the map, given an array of nodes returned by getChildNodes(). Under the DOM spec, this is a member function named getLength.

Syntax

size_t getNodeMapLength(const xmlnodes *nodes);

Parameter	IN / OUT	Description
nodes	(IN)	array of nodes

getNodeName()

Description

Returns the name of the given node, or NULL if the node has no name. Note that "tagname" and "name" are currently synonymous.

Syntax

const oratext* getNodeName(const xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	pointer to node

getNodeType()

Description

Returns the type code for a node.

Syntax

xmlntype getNodeType( const xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	pointer to node

getNodeValue()

Description

Returns the "value" (associated character data) for a node, or NULL if the node has no data.

Syntax

const oratext* getNodeValue( const xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	pointer to node

getNotationPubID()

Description

Return a notation node's public ID. Under the DOM spec, this is a method named getPublicId().

Syntax

const oratext *getNotationPubID( const xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	pointer to node

getNotationSysID()

Description

Return a notation node's system ID. Under the DOM spec, this is a method named getSystemId().

Syntax

const oratext *getNotationSysID( const xmlnode *note);

Parameter	IN / OUT	Description
node	(IN)	pointer to node

getOwnerDocument()

Description

Returns the document node which contains the given node. An XML document is always rooted in a node of type DOCUMENT_NODE. Calling getOwnerDocument() on any node in the document returns that document node.

Syntax

xmlnode* getOwnerDocument( xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	pointer to node

getParentNode()

Description

Returns the parent node of the given node. For the top-most node, NULL is returned.

Syntax

xmlnode* getParentNode( const xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	pointer to node

getPIData()

Description

Returns a Processing Instruction's (PI) data string. Under the DOM spec, this is a method named getData().

Syntax

const oratext *getPIData( const xmlnode *pi);

Parameter	IN / OUT	Description
pi	(IN)	pointer to PI node

getPITarget()

Description

Returns a Processing Instruction's (PI) target string. Under the DOM spec, this is a method named getTarget().

Syntax

const oratext *getPITarget( const xmlnode *pi);

Parameter	IN / OUT	Description
pi	(IN)	pointer to PI node

getPreviousSibling()

Description

Returns the previous sibling of the given node; the node at the same level which came before this one. For the first child of a node, NULL is returned.

Syntax

xmlnode* getPreviousSibling( const xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	pointer to node

getTagName()

Description

Returns the "tagname" of a node, which is the same as its name for now, see getNodeName. The DOM specification states that "...even though there is a generic nodeName attribute on the Node interface, there is still a tagName attribute on the Element interface; these two attributes must contain the same value, but the Working Group considers it worthwhile to support both, given the different constituencies the DOM API must satisfy."

Syntax

const oratext *getTagName( const xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	pointer to node

hasAttributes()

Description

Determines if the given node has any defined attributes, returning TRUE if so, FALSE if not. This is a DOM extension named after the pattern started by hasChildNodes().

Syntax

boolean hasAttributes( const xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	pointer to node

hasChildNodes()

Description

Determines if the given node has children, returning TRUE if so, FALSE if not. The same result can be achieved by testing if getChildNodes() returns a pointer (has children) or NULL (no children).

Syntax

boolean hasChildNodes( const xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	pointer to node

hasFeature()

Description

Tests if the DOM implementation implements a specific feature and version. feature is the package name of the feature to test. In DOM Level 1, the legal values are "HTML" and "XML" (case-insensitive). version is the version number of the package name to test. In DOM Level 1, this 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 hasFeature( xmlctx *ctx,
                    const oratext *feature, 
                    const oratext *version);

Parameter	IN / OUT	Description
ctx	(IN)	XML context
feature	(IN)	the package name of the feature to test
version	(IN)	the version number of the package name to test

importNode()

Description

Imports a node from another document to this document. The returned node has no parent; it is NULL. The source node is not altered or removed from the original document; this method creates a new copy of the source node. If deep is TRUE, recursively imports the subtree under node; if it's FALSE, imports only the node itself.

Additional information is copied as appropriate to the nodeType, attempting to mirror the behavior expected if a fragment of XML source was copied from one document to another, recognizing that two documents may have different DTDs. See DOM 2.0 spec for specific action taken for each node type.

Syntax

xmlnode *importNode( xmlctx *ctx,
                     xmlnode *import,
                     boolean deep);

Parameter	IN / OUT	Description
ctx	(IN)	XML context
import	(IN)	node to be imported
deep	(IN)	recursively import subtree?

insertBefore()

Description

Inserts a new node into the given parent node's list of children before the existing reference node. If the reference node is NULL, appends the new node at the end of the list. If the new node is a DocumentFragment, its children are inserted, in the same order, instead of the fragment itself. If the new node is already in the tree, it is first removed.

Syntax

xmlnode *insertBefore( xmlctx *ctx,
                       xmlnode *parent,
                       xmlnode *newChild,
                       xmlnode *refChild);

Parameter	IN / OUT	Description
ctx	(IN)	XML context
parent	(IN)	parent node into which new node will be inserted
newChild	(IN)	new child node to insert
refChild	(IN)	reference node before which insertion occurs

insertData()

Description

Inserts a string into the node character data at the specified offset.

Syntax

void insertData( xmlctx *ctx,
                 xmlnode *node,
                 ub4 offset,
                 const oratext *arg);

Parameter	IN / OUT	Description
ctx	(IN)	XML context
node	(IN)	pointer to node
offset	(IN)	insertion point, 0 is first position
arg	(IN)	new string to insert

isStandalone()

Description

Returns the value of the standalone flag as specified in the document's <?xml?> processing instruction. This is an invented function, not in DOM spec, but named to match the DOM pattern.

Syntax

boolean isStandalone( xmlctx *ctx);

Parameter	IN / OUT	Description
ctx	(IN)	XML context

nodeValid()

Description

Validates a node against the DTD. Returns 0 on success, else a nonzero error code (which can be looked up in the message file). This function is provided for applications which construct their own documents using the API or Class Generator, or both.. Normally the parser will validate the document and the user need not call nodeValid explicitly.

Syntax

uword nodeValid( xmlctx *ctx,
                 const xmlnode *node);

Parameter	IN / OUT	Description
ctx	(IN)	XML context
node	(IN)	pointer to node

normalize()

Description

"Normalizes" an element, or merges adjacent TEXT nodes. Adjacent TEXT nodes don't happen during a normal parse, only when extra nodes are inserted using the DOM.

Syntax

void normalize( xmlctx *ctx,
                xmlnode *elem);

Parameter	IN / OUT	Description
ctx	(IN)	XML context
elem	(IN)	pointer to element node

numAttributes()

Description

Returns the number of defined attributes in an attribute array (as returned by getAttributes). This is an invented function, not in the DOM spec, but named after the DOM pattern.

Syntax

size_t numAttributes( const xmlnodes *attrs);

Parameter	IN / OUT	Description
attrs	(IN)	array of attributes

numChildNodes()

Description

Returns the number of children in an array of nodes (as returned by getChildNodes). This is an invented function, not in the DOM spec, but named after the DOM pattern.

Syntax

size_t numChildNodes(const xmlnodes *nodes);

Parameter	IN / OUT	Description
nodes	(IN)	pointer to opaque nodes structure

prefixToURI()

Description

Returns the matching URI given a namespace prefix and a node. If the given node doesn't have a matching prefix, its parent is tried, then *its* parent, and so on, all the way to the root node. If the prefix is undefined, NULL is returned.

Syntax

oratext *prefixToURI( xmlnode *node,
                      oratext *prefix);

Parameter	IN / OUT	Description
node	(IN)	Starting node
prefix	(IN)	Prefix to match

removeAttribute()

Description

Removes the named attribute from an element node. If the removed attribute has a default value it is immediately replaced.

Syntax

void removeAttribute( xmlnode *elem,
                      const oratext *name);

Parameter	IN / OUT	Description
elem	(IN)	pointer to element node
name	(IN)	name of attribute to remove

removeAttributeNode()

Description

Removes an attribute from an element, given a pointer to the attribute. If successful, returns the attribute node back. On error, returns NULL.

Syntax

xmlnode *removeAttributeNode( xmlnode *elem,
                              xmlnode *attr);

Parameter	IN / OUT	Description
elem	(IN)	pointer to element node
attr	(IN)	attribute node to remove

removeChild()

Description

Removes the given node from its parent and returns it.

Syntax

xmlnode *removeChild( xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	old node to remove

removeNamedItem()

Description

Removes the named node from an array of nodes.

Syntax

xmlnode *removeNamedItem( xmlnodes *nodes,
                          const oratext *name);

Parameter	IN / OUT	Description
nodes	(IN)	list of nodes
name	(IN)	name of node to remove

replaceChild()

Description

Replaces an existing child node with a new node and returns the old node. If the new node is already in the tree, it is first removed.

Syntax

xmlnode *replaceChild( xmlctx *ctx,
                       xmlnode *newChild, 
                       xmlnode *oldChild);

Parameter	IN / OUT	Description
ctx	(IN)	XML context
newChild	(IN)	new replacement node
oldChild	(IN)	old node being replaced

replaceData()

Description

Replaces the substring at the given character offset and length with a replacement string.

Syntax

void replaceData( xmlctx *ctx,
                  xmlnode *node,
                  ub4 offset,
                  ub4 count,
                  oratext *arg);

Parameter	IN / OUT	Description
ctx	(IN)	XML context
node	(IN)	pointer to node
offset	(IN)	start of substring to replace (0 is first character)
count	(IN)	length of old substring
arg	(IN)	replacement text

saveString()

Description

Saves a character string in the XML memory pool. The memory will be freed after an xmlclean or xmlterm call.

Syntax

oratext *saveString( xmlctx *ctx,
                     oratext *str);

Parameter	IN / OUT	Description
ctx	(IN)	XML context
str	(IN)	string to save

saveString2()

Description

Allocates memory and saves the NULL-terminated Unicode string in the XML string pool. Note that a Unicode string is terminated with TWO NULL bytes, not just one! Strings saved this way cannot be freed individually since they are stored head-to-tail in a single pool, for maximum compactness. The memory is reused only when the entire pool is freed, after an xmlclean() or xmlterm() calls. Use saveString() for saving single or multibyte strings.

Syntax

ub2 *saveString2( xmlctx *ctx,
                  ub2 *ustr);

Parameter	IN / OUT	Description
xtx	(IN)	LPX context
ustr	(IN)	Pointer to a unicode string

setAttribute()

Description

Creates a new attribute for an element. If the named attribute already exists, its value is simply replaced.

Syntax

xmlnode *setAttribute( xmlctx *ctx,
                       xmlnode *elem,
                       const oratext *name,
                       const oratext *value);

Parameter	IN / OUT	Description
ctx	(IN)	XML context
elem	(IN)	pointer to element node
name	(IN)	name of new attribute
value	(IN)	value of new attribute

setAttributeNode()

Description

Adds a new attribute to the given element. If the named attribute already exists, it is replaced and the user's old pointer (if provided) is set to the old attr. If the attribute is new, it is added and the old pointer is set to NULL. Returns a truth value indicating success.

Syntax

boolean setAttributeNode( xmlctx *ctx,
                          xmlnode *elem,
                          xmlnode *newNode,
                          xmlnode **oldNode);

Parameter	IN / OUT	Description
ctx	(IN)	XML context
elem	(IN)	pointer to element node
newNode	(IN)	pointer to new attribute
oldNode	(OUT)	return pointer for old attribute

setAttrValue()

Description

Sets an attribute's value.

Syntax

void setAttrValue( xmlnode *attr,
                   const oratext *data);

Parameter	IN / OUT	Description
attr	(IN)	attribute whose value must be set
data	(IN)	new value for attribute

setCharData()

Description

Sets a TEXT or CDATA node's value.

Syntax

void setCharData( xmlnode *node,
                  const oratext *data);

Parameter	IN / OUT	Description
node	(IN)	node whose data must be set
data	(IN)	new text for node

setNamedItem()

Description

Sets a new child node in a parent node's map; if an old node exists with same name, replaces the old node (and sets user's pointer, if provided, to it); if no such named node exists, appends node to map and sets pointer to NULL.

Syntax

boolean setNamedItem( xmlctx *ctx,
                      xmlnode *parent,
                      xmlnode *node,
                      xmlnode **old);

Parameter	IN / OUT	Description
ctx	(IN)	XML context
parent	(IN)	parent to add node to
node	(IN)	new node to add
old	(IN)	pointer to replaced node

setNodeValue()

Description

Sets the value (character data) associated with a node.

Syntax

boolean setNodeValue( xmlnode *node,
                      const oratext *data);

Parameter	IN / OUT	Description
node	(IN)	pointer to node
data	(IN)	new data for node

setPIData()

Description

Sets a Processing Instruction's (PI) data (equivalent to setNodeValue). It is not permitted to set the data to NULL. Under the DOM spec, this is a method named setData().

Syntax

void setPIData( xmlnode *pi,
                const oratext *data);

Parameter	IN / OUT	Description
pi	(IN)	pointer to PI node
data	(IN)	new data for PI

splitText()

Description

Breaks a TEXT node into two TEXT nodes at the specified offset, keeping both in the tree as siblings. The original node then only contains all the content up to the offset point. And a new node, which is inserted as the next sibling of the original, contains all the old content starting at the offset point.

Syntax

xmlnode *splitText( xmlctx *ctx,
                    xmlnode *old,
                    uword offset);

Parameter	IN / OUT	Description
ctx	(IN)	XML context
old	(IN)	original node to split
offset	(IN)	offset of split point

substringData()

Description

Returns a substring of a node's character data.

Syntax

const oratext *substringData( xmlctx *ctx,
                              const xmlnode *node, 
                              ub4 offset,
                              ub4 count);

Parameter	IN / OUT	Description
ctx	(IN)	XML context
node	(IN)	pointer to node
offset	(IN)	offset of start of substring
count	(IN)	length of substring

---

Namespace APIs

---

Description of Namespace APIs

Namespace APIs provide an interface that is an extension to the DOM and give information relating to the document namespaces.

• XML namespaces provide a simple method for qualifying element and attribute names used in Extensible Markup Language documents by associating them with namespaces identified by URI references. A single XML document may contain elements and attributes (here referred to as a "markup vocabulary") that are defined for and used by multiple software modules. One motivation for this is modularity; if such a markup vocabulary exists which is well-understood and for which there is useful software available, it is better to reuse this markup rather than re-invent it.
• Such documents, containing multiple markup vocabularies, pose problems of recognition and collision. Software modules need to be able to recognize the tags and attributes which they are designed to process, even in the face of "collisions" occurring when markup intended for some other software package uses the same element type or attribute name.
• These considerations require that document constructs should have universal names, whose scope extends beyond their containing document. This C implementation of XML namespaces provides a mechanism to accomplish this.
• Names from XML namespaces may appear as qualified names, which contain a single colon, separating the name into a namespace prefix and a local part. The prefix, which is mapped to a URI reference, selects a namespace. The combination of the universally managed URI namespace and the document's own namespace produces identifiers that are universally unique. Mechanisms are provided for prefix scoping and defaulting.
• URI references can contain characters not allowed in names, so cannot be used directly as namespace prefixes. Therefore, the namespace prefix serves as a proxy for a URI reference. An attribute-based Syntax described in the W3C Namespace specification is used to declare the association of the namespace prefix with a URI reference.
• The implementation of this C Namespace interface followed the XML Namespace standard of revision REC-xml-names-19990114.

---

Functions of Namespace APIs

Table 13-8 Summary of Functions of Namespace APIs  

Function	Description
getAttrLocal()	Returns attribute local name.
getAttrNamespace()	Returns attribute namespace (URI).
getAttrPrefix()	Returns attribute prefix.
getAttrQualifiedName()	Returns attribute fully qualified name.
getNodeLocal()	Returns node local name.
getNodeNamespace()	Returns node namespace (URI).
getNodePrefix()	Returns node prefix.
getNodeQualifiedName()	Returns node qualified name.

getAttrLocal()

Description

Returns the local name of this attribute.

Syntax

const oratext *getAttrLocal( const xmlattr *attr);

Parameter	IN / OUT	Description
attr	(IN)	pointer to opaque attribute structure; see getAttribute()

getAttrNamespace()

Description

Returns namespace for this attribute.

Syntax

const oratext *getAttrNamespace( const xmlattr *attr); 

Parameter	IN / OUT	Description
attr	(IN)	pointer to opaque attribute structure; see getAttribute()

getAttrPrefix()

Description

Returns prefix for this attribute.

Syntax

const oratext *getAttrPrefix( const xmlattr *attr); 

Parameter	IN / OUT	Description
attr	(IN)	pointer to opaque attribute structure; see getAttribute()

getAttrQualifiedName()

Description

Returns fully qualified name for the attribute.

Syntax

const oratext *getAttrQualifiedName( const xmlattr *attr); 

Parameter	IN / OUT	Description
attr	(IN)	pointer to opaque attribute structure; see getAttribute()

getNodeLocal()

Description

This function returns the local name of this node.

Syntax

const oratext *getNodeLocal( const xmlnode *node);

Parameter	IN / OUT	Description
node	(IN)	node from which local name is retrieved

getNodeNamespace()

Description

Returns namespace for this node.

Syntax

const oratext *getNodeNamespace( const xmlnode *node); 

Parameter	IN / OUT	Description
node	(IN)	node from which namespace is retrieved

getNodePrefix()

Description

Returns prefix for this node.

Syntax

const oratext *getNodePrefix( const xmlnode *node); 

Parameter	IN / OUT	Description
node	(IN)	node from which prefix is retrieved

getNodeQualifiedName()

Description

Returns fully qualified name for this node.

Syntax

const oratext *getNodeQualifiedName( const xmlnode *node); 

Parameter	IN / OUT	Description
node	(IN)	node from which name is retrieved