14
XML Parser for C

This chapter describes the C language implementation of XML Parser.

This chapter contains the following sections:

Parser APIs

Extensible Markup Language (XML) describes a class of data objects called XML documents and partially describes the behavior of computer programs which process them. XML is an application profile or restricted form of SGML, the Standard Generalized Markup Language [ISO 8879]. By construction, XML documents are conforming SGML documents.

XML documents are made up of storage units called entities, which contain either parsed or unparsed data. Parsed data is made up of characters, some of which form character data, and some of which form markup. Markup encodes a description of the document's storage layout and logical structure. XML provides a mechanism to impose constraints on the storage layout and logical structure. A software module called an XML processor is used to read XML documents and provide access to their content and structure. It is assumed that an XML processor is doing its work on behalf of another module, called the application.

This C implementation of the XML processor (or parser) followed the W3C XML specification (rev REC-xml-19980210) and included 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.

The following is the default behavior of this parser:

The character set encoding is UTF-8. If all your documents are ASCII, you are encouraged to set the encoding to US-ASCII for better performance.
Messages are printed to stderr unless msghdlr is given.
A parse tree which can be accessed by DOM APIs is built unless saxcb is set to use the SAX callback APIs. Note that any of the SAX callback functions can be set to NULL if not needed.
The default behavior for the parser is to check that the input is well-formed but not to check whether it is valid. The flag XML_FLAG_VALIDATE can be set to validate the input. The default behavior for whitespace processing is to be fully conformant to the XML 1.0 spec, i.e. all whitespace is reported back to the application but it is indicated which whitespace is ignorable. However, some applications may prefer to set the XML_FLAG_DISCARD_WHITESPACE which will discard all whitespace between an end-element tag and the following start-element tag.

Calling Sequence

Parsing a single document:

xmlinit, xmlparsexxx, xmlterm

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

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

Parsing multiple documents, all document data must be available:

xmlinit, xmlparsexxx, xmlparsexxx ... xmlterm

Memory

The memory callback functions specified in memcb may be used if you wish to use your own memory allocation. If they are used, all of the 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:

xmlparsexxx is called to parse another document.
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.

Table 14-1 summarizes the methods of the C parser.

Table 14-1 Summary of the Methods of the C Parser

Method	Description
xmlinit()	Initialize XML parser
xmlclean()	Clean up memory used during parse
xmlparse()	Parse a document specified by a URL
xmlparsebuf()	Parse a document that's resident in memory
xmlparsefile()	Parse a document from the filesystem
xmlparsestream()	Parse a document from a user-defined stream
xmlterm()	Shut down XML parser
createDocument()	Create a new document
isStandalone()	Return document's standalone flag
isSingleChar()	Return single/multibyte encoding flag
getEncoding()	Return name of document's encoding

xmlinit()

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, non-zero 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.

Error codes are: XMLERR_LEH_INIT, XMLERR_BAD_ENCODING, XMLERR_NLS_INIT, XMLERR_NO_MEMORY, XMLERR_NULL_PTR.

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 character set encoding is UTF-8. If all your documents are ASCII, you are encouraged to set the encoding to US-ASCII for better performance.

By default, messages are printed to stderr unless msghdlr is given.

By default, a parse tree is built (accessible by DOM APIs) unless saxcb is set (in which case the SAX callback APIs are invoked). Note that any of the SAX callback functions can be set to NULL if not needed.

The memory callback functions memcb may be used if you wish to use your own memory allocation. If they are used, all of the functions should be specified.

The Parameters msgctx, saxcbctx, and memcbctx are structures that you may define and use to pass information to your callback routines for the message handler, SAX functions, or memory functions, respectively. They should be set to NULL if your callback functions do not need any additional information passed in to them.

The lang parameter is not used currently and may be set to NULL. It will be used in future releases to determine the language of the error messages.

Syntax

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

Parameter IN/OUT Description

er

OUT

The error, if any (C only).

encoding

IN

Default character set encoding

msghdlr

IN

Error message handler function

msgctx

IN

Context for the error message handler

saxcb

IN

SAX callback stgructure filled with function pointers

saxcbctx

IN

Content of SAX callbacks

memcb

IN

Memory function callbacks

memcbctx

IN

Context for memoryfunction callbacks

lang

IN

Language for error messages

Parameter	IN/OUT	Description
er	OUT	The error, if any (C only).
encoding	IN	Default character set encoding
msghdlr	IN	Error message handler function
msgctx	IN	Context for the error message handler
saxcb	IN	SAX callback stgructure filled with function pointers
saxcbctx	IN	Content of SAX callbacks
memcb	IN	Memory function callbacks
memcbctx	IN	Context for memoryfunction callbacks
lang	IN	Language for error messages

xmlclean()

Frees memory used during the previous parse. This function is provided as a convenience for those who want to parse multiple documents using a single context. Before parsing the second and subsequent documents, call xmlclean to release memory used by the previous document.

Memory is reused internally after this call. Memory is not returned to the system until xmlterminate.

Syntax

void xmlclean(xmlctx *ctx);

Parameter IN/OUT Description

ctx

IN

The XML parser context

Parameter	IN/OUT	Description
ctx	IN	The XML parser context

xmlparse()

Invokes the XML parser on an input document that is specified by a URL. The parser must have been initialized successfully with a call to xmlinit first.

Flag bits must be OR'd to override the default behavior of the parser. The following flag bits may be set:

XML_FLAG_VALIDATE turns validation on. The default behavior is to not validate the input.
XML_FLAG_DISCARD_WHITESPACE will discard whitespace where it appears to be insignificant. The default behavior for whitespace processing is to be fully conformant to the XML 1.0 spec, i.e. all whitespace is reported back to the application but it is indicated which whitespace is ignorable. However, some applications may prefer to set the XML_FLAG_DISCARD_WHITESPACE which will discard all whitespace between an end-element tag and the following start-element tag.
XML_FLAG_DTD_ONLY tells the parser that the input is an external DTD only, not a complete document.
XML_FLAG_STOP_ON_WARNING makes the parser stop immediately if any validation warnings occur. By default, validation warnings are printed but validation continues.

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

xmlparsexxx is called to parse another document.
xmlclean is called.
xmlterm is called.

Syntax

uword xmlparse(xmlctx *ctx, const oratext *url,
               const oratext *encoding, ub4 flags);

Parameter IN/OUT Description

ctx

IN/OUT

The XML parser context

url

IN

URL of XML document

encoding

IN

default character set encoding

flags

IN

what options to use

Parameter	IN/OUT	Description
ctx	IN/OUT	The XML parser context
url	IN	URL of XML document
encoding	IN	default character set encoding
flags	IN	what options to use

xmlparsebuf()

Invokes the XML parser on a document that is resident in memory. The parser must have been initialized successfully with a call to xmlinit first. This function is identical to xmlparse except that input is taken from the user's buffer instead of from a URI, file, and so on.

Syntax

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

Parameter IN/OUT Description

ctx

IN/OUT

The XML parser context

buffer

IN

pointer to document in memory

len

IN

length of the buffer

encoding

IN

default character set encoding

flags

IN

what options to use

Parameter	IN/OUT	Description
ctx	IN/OUT	The XML parser context
buffer	IN	pointer to document in memory
len	IN	length of the buffer
encoding	IN	default character set encoding
flags	IN	what options to use

xmlparsefile()

Invokes the XML parser on a document in the filesystem. The parser must have been initialized successfully with a call to xmlinit first. This function is identical to xmlparse except that input is taken from a file in the user's filesystem, instead of from a URL, memory buffer, and so on.

Syntax

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

Parameter IN/OUT Description

ctx

IN/OUT

The XML parser context

path

IN

filesystem path of document

encoding

IN

default character set encoding

flags

IN

what options to use

Parameter	IN/OUT	Description
ctx	IN/OUT	The XML parser context
path	IN	filesystem path of document
encoding	IN	default character set encoding
flags	IN	what options to use

xmlparsestream()

Invokes the XML parser on a document that is to be read from a user-defined stream. The parser must have been initialized successfully with a call to xmlinit first. This function is identical to xmlparse except that input is taken from a user-defined stream, instead of from a URL, file, etc. 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 void *stream,
                     const oratext *encoding, ub4 flags);

Parameter IN/OUT Description

ctx

IN/OUT

The XML parser context

stream

IN

pointer to stream or stream context

encoding

IN

default character set encoding

flags

IN

what options to use

Parameter	IN/OUT	Description
ctx	IN/OUT	The XML parser context
stream	IN	pointer to stream or stream context
encoding	IN	default character set encoding
flags	IN	what options to use

xmlterm()

Terminates the XML parser. It should be called after xmlinit, and before exiting the main program. This function will free all memory used by the parser and terminates the context, which may not then be reused (a new context must be created if additional parsing is to be done).

Syntax

uword xmlterm(xmlctx *ctx);

Parameter IN/OUT Description

ctx

IN

XML parser context

Parameter	IN/OUT	Description
ctx	IN	XML parser context

createDocument()

Creates a new document in memory. This function is used when constructing 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.

Syntax

xmlnode* createDocument(xmlctx *ctx)

Parameter IN/OUT Description

ctx

IN

XML parser context

Parameter	IN/OUT	Description
ctx	IN	XML parser context

isStandalone()

Return value of document's standalone flag. This function returns the boolean value of the document's standalone flag, as specified in the <?xml?> processing instruction.

Syntax

boolean isStandalone(xmlctx *ctx)

Parameter IN/OUT Description

ctx

IN

XML parser context

Parameter	IN/OUT	Description
ctx	IN	XML parser context

isSingleChar()

Returns a flag which specifies whether the current document is encoded as single-byte characters, ASCII, or multi-byte characters, UTF-8. Compare to getEncoding, which Returns the actual name of the document's encoding.

Syntax

boolean isSingleChar(xmlctx *ctx)

Parameter IN/OUT Description

ctx

IN

XML parser context

Parameter	IN/OUT	Description
ctx	IN	XML parser context

getEncoding()

Returns the name of the current document's character encoding scheme, such as ASCII, UTF8, and so on. Compare to isSingleChar which just Returns a boolean flag saying whether the current encoding is single or multi-byte.

Syntax

oratext *getEncoding(xmlctx *ctx)

Parameter IN/OUT Description

ctx

IN

XML parser context

Parameter	IN/OUT	Description
ctx	IN	XML parser context

XSLT API

XSLT is a language for transforming XML documents into other XML documents.

XSLT is designed for use as part of XSL, which is a stylesheet language for XML. In addition to XSLT, XSL includes an XML vocabulary for specifying formatting. XSL specifies the styling of an XML document by using XSLT to describe how the document is transformed into another XML document that uses the formatting vocabulary.

XSLT is also designed to be used independently of XSL. However, XSLT is not intended as a completely general-purpose XML transformation language. Rather it is designed primarily for the kinds of transformation that are needed when XSLT is used as part of XSL.

A transformation expressed in XSLT describes rules for transforming a source tree into a result tree. The transformation is achieved by associating patterns with templates. A pattern is matched against elements in the source tree. A template is instantiated to create part of the result tree. The result tree is separate from the source tree. The structure of the result tree can be completely different from the structure of the source tree. In constructing the result tree, elements from the source tree can be filtered and reordered, and arbitrary structure can be added.

A transformation expressed in XSLT is called a stylesheet. This is because, in the case when XSLT is transforming into the XSL formatting vocabulary, the transformation functions as a stylesheet.

A stylesheet contains a set of template rules. A template rule has two parts: a pattern which is matched against nodes in the source tree and a template which can be instantiated to form part of the result tree. This allows a stylesheet to be applicable to a wide class of documents that have similar source tree structures.

A template is instantiated for a particular source element to create part of the result tree. A template can contain elements that specify literal result element structure. A template can also contain elements from the XSLT namespace that are instructions for creating result tree fragments. When a template is instantiated, each instruction is executed and replaced by the result tree fragment that it creates. Instructions can select and process descendant source elements. Processing a descendant element creates a result tree fragment by finding the applicable template rule and instantiating its template. Note that elements are only processed when they have been selected by the execution of an instruction. The result tree is constructed by finding the template rule for the root node and instantiating its template.

A software module called an XSL processor is used to read XML documents and transform them into other XML documents with different styles.

The C implementation of the XSL processor followed the XSL Transformations standard (version 1.0, November 16, 1999) and included the required behavior of an XSL processor as specified in the XSLT specification.

xslprocess()

Processes XSL Stylesheet with XML document source and Returns success or an error code.

Syntax

uword xslprocess(xmlctx *docctx, xmlctx *xslctx,
                 xmlctx *resctx, xmlnode **result);

Parameter IN/OUT Description

xmlctx

IN/OUT

The XML document context

xslctx

IN

The XSL stylesheet context

resctx

IN

The result document fragment context

result

IN/OUT

The result document fragment node

Parameter	IN/OUT	Description
xmlctx	IN/OUT	The XML document context
xslctx	IN	The XSL stylesheet context
resctx	IN	The result document fragment context
result	IN/OUT	The result document fragment node

W3C SAX APIs

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

There are two major types of XML (or SGML) APIs:

tree-based APIs, and
event-based APIs.

A tree-based API compiles an XML document into an internal tree structure, then allows an application to navigate that tree using the Document Object Model (DOM), a standard tree-based API for XML and HTML documents.

An event-based API, on the other hand, reports parsing events (such as the start and end of elements) directly to the application through callbacks, and does not usually build an internal tree. The application implements handlers to deal with the different events, much like handling events in a graphical user interface.

Tree-based APIs are useful for a wide range of applications, but they often put a great strain on system resources, especially if the document is large (under very controlled circumstances, it is possible to construct the tree in a lazy fashion to avoid some of this problem). Furthermore, some applications need to build their own, different data trees, and it is very inefficient to build a tree of parse nodes, only to map it onto a new tree.

In both of these cases, an event-based API provides a simpler, lower-level access to an XML document: you can parse documents much larger than your available system memory, and you can construct your own data structures using your callback event handlers.

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.

The SAX callback structure:

typedef struct
{
   sword (*startDocument)(void *ctx);
   sword (*endDocument)(void *ctx);
   sword (*startElement)(void *ctx, const oratext *name,
                         const struct xmlarray *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);
} xmlsaxcb;

Table 14-2 summarizes the callback functions. Note that all functions with the exception of nsStartElement() conform to the SAX standard.

Table 14-2 Summary of SAX Callback functions.

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

characters()

This callback function 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

client context pointer

ch

IN

the characters

len

IN

number of characters to use from the character pointer

Parameter	IN/OUT	Description
ctx	IN	client context pointer
ch	IN	the characters
len	IN	number of characters to use from the character pointer

endDocument()

This callback function receives notification of the end of the document.

Syntax

sword (*endDocument)(
   void *ctx);

Parameter IN/OUT Description

ctx

IN

client context

Parameter	IN/OUT	Description
ctx	IN	client context

endElement()

This callback function 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

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

ignorableWhitespace()

This callback function 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

client context

ch

IN

whitespace characters

len

IN

number of characters to use from the character pointer

Parameter	IN/OUT	Description
ctx	IN	client context
ch	IN	whitespace characters
len	IN	number of characters to use from the character pointer

notationDecl ()

Purpose

This callback function 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

client context

name

IN

notation name

publicId

IN

notation public identifier, or null if not available

systemId

IN

notation system identifier

Parameter	IN/OUT	Description
ctx	IN	client context
name	IN	notation name
publicId	IN	notation public identifier, or null if not available
systemId	IN	notation system identifier

processingInstruction()

This callback function receives notification of a processing instruction.

Syntax

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

Parameter IN/OUT Description

ctx

IN

client context

target

IN

processing instruction target

data

IN

processing instruction data, or null if none is supplied

Parameter	IN/OUT	Description
ctx	IN	client context
target	IN	processing instruction target
data	IN	processing instruction data, or null if none is supplied

startDocument()

This callback function receives notification of the beginning of the document.

Syntax

sword (*startDocument)(
   void *ctx);

Parameter IN/OUT Description

ctx

IN

client context

Parameter	IN/OUT	Description
ctx	IN	client context

startElement()

This callback function receives notification of the beginning of an element.

Syntax

word (*startElement)(
   void *ctx,
   const oratext *name,
   const struct xmlattrs *attrs);

Parameter IN/OUT Description

ctx

IN

client context

name

IN

element type name

attrs

IN

specified or defaulted attributes

Parameter	IN/OUT	Description
ctx	IN	client context
name	IN	element type name
attrs	IN	specified or defaulted attributes

unparsedEntityDecl()

This callback function 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

client context

name

IN

entity name

publicId

IN

entity public identifier, or null if not available

systemId

IN

entity system identifier

notationName

IN

name of the associated notation

Parameter	IN/OUT	Description
ctx	IN	client context
name	IN	entity name
publicId	IN	entity public identifier, or null if not available
systemId	IN	entity system identifier
notationName	IN	name of the associated notation

nsStartElement()

This callback function receives notification of the start of a namespace for an element.

Syntax

sword (*nsStartElement)(
   void *ctx,
   const oratext *qname,
   const oratext *local,
   const oratext *namespace,
   const struct xmlattrs *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

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

The Document Object Model (DOM) is an application programming interface (API) for HTML and XML documents. It defines the logical structure of documents and the way a document is accessed and manipulated. In the DOM specification, the term document is used in the broad sense -- increasingly, XML is being used as a way of representing many different kinds of information that may be stored in diverse systems, and much of this would traditionally be seen as data rather than as documents. Nevertheless, XML presents this data as documents, and the DOM may be used to manage this data.

With the DOM, programmers can build documents, navigate their structure, and add, modify, or delete elements and content. Anything found in an HTML or XML document can be accessed, changed, deleted, or added using the DOM, with a few exceptions -- in particular, the DOM interfaces for the XML internal and external subsets have not yet been specified.

One important objective of the W3C specification for the DOM is to provide a standard programming interface that can be used in a wide variety of environments and applications. The DOM is designed to be used with any programming language. Since the DOM standard is object-oriented, for the C adaptation, some changes had to be made:

Reused function names had to be expanded, e.g. getValue in the attribute class is given the unique name getAttrValue, matching the pattern established by getNodeValue.
Also, some functions were added to extend the DOM. For example, there is no function defined which Returns the number of children of a node, so numChildNodes was invented, etc.

The implementation of this C DOM interface follows REC-DOM-Level-1-19981001. Table 14-3 summarizes the C DOM functions.

Table 14-3 Summary of W3C DOM Methods

Method	Description
appendChild()	Append child node to current node
appendData()	Append character data to end of node's current data
cloneNode()	Create a new node identical to the current one
createAttribute()	Create an new attribute for an element node
createCDATASection()	Create a CDATA node
createComment()	Create a comment node
createDocumentFragment()	Create a document fragment node
createElement()	Create an element node
createEntityReference()	Create an entity reference node
createProcessingInstruction()	Create a processing instruction (PI) node
createTextNode()	Create a text ode
deleteData()	Remove substring from a node's character data
getAttribute()	Return an attribute's name
getAttributeIndex()	Return value of attribute's specified flag.
getAttributeNode()	Return an attribute's value (definition).
getAttributes()	Return the value of an attribute
getAttrName()	Return an element's attribute given its index
getAttrSpecified()	Get an element's attribute node given its name.
getAttrValue()	Return array of element's attributes
getCharData()	Return character data for a TEXT node.
getCharLength()	Return length of TEXT node's character data.
getChildNode()	Return indexed node from array of nodes.
getChildNodes()	Return array of node's children
getContentModel()	Returns the content model for an element from the DTD.
getDocType()	Return top-level DOCUMENT node.
getDocTypeEntities()	Return highest-level (root) ELEMENT node.
getDocTypeName()	Return current DTD.
getDocTypeNotations()	Return array of DTD's general entities
getElementsByTagName()	Return name of DTD
getDocument()	Return array of DTD's notations
getDocumentElement()	Return list of elements with matching name
getEntityNotation()	Return an entity's NDATA.
getEntityPubID()	Return an entity's public ID.
getEntitySysID()	Return an entity's system ID.
getFirstChild()	Return the first child of a node
getImplementation()	Return DOM-implementation structure (if defined)
getLastChild()	Return the last child of a node
getNamedItem()	Return a node's next sibling
getNextSibling()	Returns the named node from a list of nodes
getNodeMapLength()	Returns number of entries in a NodeMap.
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.
getNotationSysID()	Returns a notation's system ID.
getOwnerDocument()	Returns the DOCUMENT node containing the given node
getParentNode()	Returns a processing instruction's data.
getPIData()	Returns a processing instruction's target.
getPITarget()	Returns a node's parent node
getPreviousSibling()	Returns a node's "previous" sibling
getTagName()	Returns a node's "gagman", same as name for now
hasAttributes()	Determine if element node has attributes
hasChildNodes()	Determine if node has children
hasFeature()	Determine if DOM implementation supports a specific feature
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
nodeValid()	Validate a node against the current DTD
normalize()	Normalize a node by merging adjacent TEXT nodes
numAttributes()	Returns number of element node's attributes
numChildNodes()	Returns number of node's children
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
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
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
setPIData()	Split a node's character data into two parts
substringData()	Return a substring of a node's character data

appendChild()

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

newnode

(IN)

new node to append

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

appendData()

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

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

cloneNode()

Returns a duplicate of this node, i.e., serves as a generic copy constructor for nodes. The duplicate node has no parent (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 differs in that the node's children are also recursively cloned instead of just 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

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

createAttribute()

Create 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

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

createCDATASection()

Create a new CDATA node.

Syntax

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

Parameter IN/OUT Description

ctx

(IN)

XML context

data

IN

CData body

Parameter	IN/OUT	Description
ctx	(IN)	XML context
data	IN	CData body

createComment()

Create 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

Parameter	IN/OUT	Description
ctx	IN	XML context
data	IN	text of comment

createDocumentFragment()

Create 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

Parameter	IN/OUT	Description
ctx	IN	XML context

createElement()

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

Parameter	IN/OUT	Description
ctx	IN	XML context
elname	IN	name of new element

createEntityReference()

Create 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 reference

Parameter	IN/OUT	Description
ctx	IN	XML context
name	IN	name of entity reference

createProcessingInstruction()

Create 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

Parameter	IN/OUT	Description
ctx	IN	XML context
target	IN	PI target
data	IN	PI definition

createTextNode()

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

Parameter	IN/OUT	Description
ctx	IN	XML context
data	IN	data for node

deleteData()

Delete 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 (o for first char)

count

IN

length of substring

Parameter	IN/OUT	Description
ctx	IN	XML context
node	IN	pointer to Node
offset	IN	offset of start of substring (o for first `char`)
count	IN	length of substring

getAttribute()

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

Syntax

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

Parameter IN/OUT Description

node

IN

Node whose attributes are scanned

name

IN

name of the attribute

Parameter	IN/OUT	Description
node	IN	Node whose attributes are scanned
name	IN	name of the attribute

getAttributeIndex()

Returns one attribute from an array of attributes, given an index (starting at 0). Fetch the attribute name and/or value (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 Node structure

index

IN

Zero-based attribute number to return

Parameter	IN/OUT	Description
attrs	IN	pointer to attribute Node structure
index	IN	Zero-based attribute number to return

getAttributeNode()

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

Parameter	IN/OUT	Description
elem	IN	pointer to Element node
name	IN	name of attribute

getAttributes()

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

the node whose attributes are returned

Parameter	IN/OUT	Description
node	IN	the node whose attributes are returned

getAttrName()

Given a pointer to an attribute, Returns the name of the 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

Parameter	IN/OUT	Description
attr	IN	pointer to attribute

getAttrSpecified()

Return 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

Parameter	IN/OUT	Description
attr	IN	pointer to attribute

getAttrValue()

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

Parameter	IN/OUT	Description
attr	IN	pointer to attribute

getCharData()

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 node

Parameter	IN/OUT	Description
node	IN	pointer to node

getCharLength()

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 node

Parameter	IN/OUT	Description
node	IN	pointer to node

getChildNode()

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

index

IN

zero-based child number

Parameter	IN/OUT	Description
nodes	IN	array of nodes
index	IN	zero-based child number

getChildNodes()

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 are returned

getContentModel()

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. See also the getModifier function which Returns the '?', '*', and '+' modifiers to content model nodes.

Syntax

xmlnode *LpxGetContentModel(xmldtd *dtd, oratext *name)

Parameter IN/OUT Description

dtd

IN

pointer to the DTD

name

IN

name of element

getDocType()

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

Syntax

xmldtd* getDocType(xmlctx *ctx)

Parameter IN/OUT Description

ctx

IN

XML parser context

getDocTypeEntities()

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()

Returns the given DTD's name.

Syntax

oratext *getDocTypeName(xmldtd* dtd)

Parameter IN/OUT Description

dtd

IN

pointer to the DTD

getDocTypeNotations()

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

getElementsByTagName()

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

name

IN

element tag name

getDocument()

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()

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

getEntityNotation()

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()

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()

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()

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()

This function 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()

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()

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 the node to fetch

index

OUT

index of found node

getNextSibling()

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()

Given an array of nodes (as returned by getChildNodes), Returns the number of nodes in the map. 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()

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

Syntax

const oratext* getNodeName(const xmlnode *node)

Parameter IN/OUT Description

node

IN

pointer to node

getNodeType()

Returns the type code for a node.

Syntax

xmlntype getNodeType(const xmlnode *node)

Parameter IN/OUT Description

node

IN

pointer to node

getNodeValue()

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()

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

Syntax

const oratext *getNotationPubID(const xmlnode *note)

Parameter IN/OUT Description

node

IN

pointer to node

getNotationSysID()

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()

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()

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()

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()

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()

Returns the previous sibling of the given node. That is, 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()

Returns the "tagname" of a node, which is the same as its name for now, see getNodeName. The DOM says "...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()

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()

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()

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

featue

IN

the name of the package

version

IN

version number of package

insertBefore()

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

newChild

IN

new child node

refChild

IN

reference node; the inserted node will come before it

insertData()

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 (first position)

refChild

IN

new string to insert

isStandalone()

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()

Validate a node against the DTD. Returns 0 on success, else a non-zero error code (which can be looked up in the message file). This function is provided for applications which construct their own documents via the API and/or Class Generator. 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()

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

Syntax

void normalize(xmlctx *ctx, xmlnode *elem)

Parameter IN/OUT Description

ctx

IN

XML context

elem

IN

pointer to element node

numAttributes()

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()

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 node structure

removeAttribute()

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()

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()

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()

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()

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()

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 the first character

count

IN

length of old substring

arg

IN

replacement text

setAttribute()

Create 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()

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

setNamedItem()

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 which the new node is added

node

IN

name of new node

old

IN

pointer to replaced node

setNodeValue()

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()

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()

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()

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

start of substring to replace; 0 is the first character

count

IN

length of substring

arg

IN

replacement text

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 re-use 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.

Table 14-4 lists the data structures and types of C Namespace.

Table 14-4 Data Structures and Types of C Namespace

Type	Definition	Description
oratext	typedef unsigned char oratext;	__
xmlattr	typedef struct xmlattr xmlattr;	The contents of `xmlattr` are private and must not be accessed by users.
xmlnode	typedef struct xmlnode xmlnode;	The contents of `xmlnode` are private and must not be accessed by users.

Table 14-5 summarizes the methods of C Namespace.

Table 14-5 Summary of Methods C Namespace

Type	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()

This function 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()

This function 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()

This function 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()

This function 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()

This function returns the local name of this node.

Syntax

const oratext *getNodeLocal(const xmlnode *node);

Parameter IN/OUT Description

node

IN

node to get local name from

getNodeNamespace()

This function returns namespace for this node.

Syntax

const oratext *getNodeNamespace(const xmlnode *node);

Parameter IN/OUT Description

node

IN

node to get namespace from

getNodePrefix()

This function returns prefix for this node.

Syntax

const oratext *getNodePrefix(const xmlnode *node);

Parameter IN/OUT Description

node

IN

node to get prefix from

getNodeQualifiedName()

This function returns fully qualified name for this node.

Syntax

const oratext *getNodeQualifiedName(const xmlnode *node);

Parameter IN/OUT Description

node

(N

node to get name from

Datatypes

Table 14-6 lists datatypes.

Table 14-6 Datatypes

Type	Definition	Description
oratext	typedef unsigned char oratext;	The basic character pointer type.
String	typedef unsigned char String;	The basic character pointer type.
xmlctx	typedef struct xmlctx xmlctx;	The top-level XML context. he 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); void (realloc)(void ctx, void ptr, size_t size); }; typedef struct xmlmemcb xmlmemcb	The memory callback structure passed to `xmlinit`.
xmlsaxcb	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 (nsStartElement)(void ctx, const oratext qname, const oratext local, const oratext namespace, const struct xmlattrs attrs); }; typedef struct xmlsaxcb xmlsaxcb;	The SAX callback structure passed to xmlinit.
ub4	typedef unsigned int ub4;	Unsigned integer with a minimum of four bytes.
uword	typedef unsigned int uword;	Unsigned integer in the native word size
boolean	typedef int boolean;
oratext	typedef unsigned char oratext;
xmlcpmod	XMLCPMOD_NONE = 0 /* no modifier / XMLCPMOD_OPT = 1 / '?' optional / XMLCPMOD_0MORE = 2 / '' zero or more / XMLCPMOD_1MORE = 3 /* '+' one or more */	Content model node modifiers, see `getModifier`.
xmlctx	typedef struct xmlctx xmlctx;	The contents of `xmlctx` are private and must not be accessed by users.
xmlnode	typedef struct xmlnode xmlnode;	The contents of `xmlnode` are private and must not be accessed by users.
xmlnodes	typedef struct xmlnodes xmlnodes;	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 = 9 / document / DOCUMENT_TYPE_NODE = 10 / DTD / DOCUMENT_FRAGMENT_NODE = 11 / document fragment/ NOTATION_NODE = 12 / notation */	Parse tree node types, see `getNodeType`. Names and values match DOM specification.

Parameter	IN/OUT	Description
ctx	IN	XML parser context
root	IN	root node
name	IN	element tag name

Parameter	IN/OUT	Description
ctx	IN	XML context
featue	IN	the name of the package
version	IN	version number of package

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

Parameter	IN/OUT	Description
ctx	IN	XML context
parent	IN	parent to which the new node is added
node	IN	name of new node
old	IN	pointer to replaced node

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

14 XML Parser for C

Parser APIs

Calling Sequence

Memory

Thread Safety

Table 14-1 Summary of the Methods of the C Parser

xmlinit()

Syntax

xmlclean()

Syntax

xmlparse()

Syntax

xmlparsebuf()

Syntax

xmlparsefile()

Syntax

xmlparsestream()

Syntax

xmlterm()

Syntax

createDocument()

Syntax

isStandalone()

Syntax

isSingleChar()

Syntax

getEncoding()

Syntax

XSLT API

xslprocess()

Syntax

W3C SAX APIs

Table 14-2 Summary of SAX Callback functions.

characters()

Syntax

endDocument()

Syntax

endElement()

Syntax

ignorableWhitespace()

Syntax

notationDecl ()

Syntax

processingInstruction()

Syntax

startDocument()

Syntax

startElement()

Syntax

unparsedEntityDecl()

Syntax

nsStartElement()

Syntax

W3C DOM APIs

Table 14-3 Summary of W3C DOM Methods

appendChild()

Syntax

appendData()

Syntax

cloneNode()

Syntax

createAttribute()

Syntax

createCDATASection()

Syntax

createComment()

Syntax

createDocumentFragment()

Syntax

createElement()

Syntax

createEntityReference()

Syntax

createProcessingInstruction()

Syntax

createTextNode()

Syntax

deleteData()

Syntax

getAttribute()

14
XML Parser for C