16
XML Parser for C++

This chapter contains the following sections:

• Attr Class
• CDATASection Class
• Comment Class
• CharacterData Class
• Document Class
• DocumentType Class
• DOMImplementation Class
• Element Class
• Entity Class
• EntityReference Class
• NamedNodeMap Class
• Node Class
• NodeList Class
• Notation Class
• ProcessingInstruction Class
• Text Class
• XMLParser Class

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

---

Attr Class

---

Description of Attr

This class contains methods for accessing the name and value of a single document node attribute.

---

Methods of Attr

Table 16-1 Summary of Methods of Attr  

Method	Description
getName()	Return name of attribute
getValue()	Return "value" (definition) of attribute
getSpecified()	Return attribute's "specified" flag value
setValue()	Set an attribute's value

getName()

Description

Returns name of attribute

Syntax

DOMString getName();

getValue()

Description

Return "value" (definition) of attribute

Syntax

DOMString getValue();

getSpecified()

Description

Returns value of attribute's "specified" flag. From the DOM. If this attribute was explicitly given a value in the original document, this is true; otherwise, it is false. Note that the implementation is in charge of this attribute, not the user. If the user changes the value of the attribute (even if it ends up having the same value as the default value) then the specified flag is automatically flipped to true. To re-specify the attribute as the default value from the DTD, the user must delete the attribute. The implementation will then make a new attribute available with specified set to false and the default value (if one exists).

Syntax

boolean getSpecified();

setValue()

Description

Sets an attribute's "value"

Syntax

void setValue(DOMString value);

Parameter	Description
value	Attribute's new value

---

CDATASection Class

---

Description of CDATASection

This class implements the CDATA node type, a subclass of Text. It inherits all of its methods from the Text Class.

---

Comment Class

Description of Comment

This class implements the COMMENT node type, a subclass of CharacterData. It inherits all of this methods from the CharacterData Class.

---

CharacterData Class

---

Description of CharacterData

This class contains methods for accessing and modifying the data associated with text nodes.

---

Methods of CharacterData

Table 16-2 Summary of Methods of CharacterData

Method	Description
appendData()	Appends a string to this node's data.
deleteData()	Deletes a substring to this text node's data.
getData()	Retrieves value of a text node.
getLength()	Returns length of a text node's data.
insertData()	Inserts a string into this node's data.
replaceData()	Replaces a substring in this node's data.
setData()	Sets value of a text node.
substringData()	Fetches a substring of this node's data.

appendData()

Description

Appends a string to this node's data.

Syntax

void appendData(DOMString arg);

Parameter	Description
arg	String to append

deleteData()

Description

Deletes a substring to this text node's data.

Syntax

void deleteData(  unsigned long offset,
                    unsigned long count);

Parameter	Description
count	Number of characters to remove
offset	Start of substring to remove (0 is the first char)

getData()

Description

Retrieves data (value) of a text node as a DOMString.

Syntax

DOMString getData();

getLength()

Description

Returns the length of a text node's data

Syntax

size_t getLength();

insertData()

Description

Inserts a string into this node's data

Syntax

void insertData(  unsigned long offset,
                    DOMString arg);

Parameter	Description
arg	String to insert.
offset	Insertion point (0 means before first character).

replaceData()

Description

Replaces a substring in this node's data.

Syntax

void replaceData(  unsigned long offset,
                      unsigned long count,
                        DOMString arg);

Parameter	Description
arg	string to insert
count	number of characters to replace
offset	insertion point (0 means before first char)

setData()

Description

Sets data, or value, of a text node.

Syntax

void setData(  DOMString data);

Parameter	Description
data	Data for node

substringData()

Description

Fetches a substring of a node's data.

Syntax

DOMString substringData(  unsigned long offset,
                            unsigned long count);

Parameter	Description
count	length of substring
offset	start of substring (0 means first char)

---

Document Class

---

Description of Document

This class contains methods for creating and retrieving nodes.

---

Methods of Document

Table 16-3 Summary of Methods of Document  

Method	Description
createAttribute()	Creates an ATTRIBUTE node.
createAttributeNS()	Create san ATTRIBUTE node with namespace information.
createCDATASection()	Creates a CDATA node.
createComment()	Creates a COMMENT node.
createDocumentFragment()	Creates a DOCUMENT_FRAGMENT node.
createElement()	Create san ELEMENT node.
createElementNS()	Creates an ELEMENT node with namespace information.
createEntityReference()	Creates an ENTITY_REFERENCE node.
createProcessingInstruction()	Create a PROCESSING_INSTRUCTION node.
createTextNode()	Creates a TEXT node.
getElementByID()	Returns the element node which has the given ID.
getElementsByTagName()	Selects nodes based on tag name.
getImplementation()	Returns DTD for document.
importNode()	Copies a node from another document into this document.
saveString()	Allocates memory and saves the given string.

createAttribute()

Description

Creates a new attribute node, and returns a pointer to that node. Use setValue() to set its value.

Syntax

Attr* createAttribute(  DOMString name,
                          DOMString value);

Parameter	Description
name	name of attribute
value	value of attribute

createAttributeNS()

Description

Creates a new attribute node with namespace information, and returns a pointer to that node. Use setValue() to set its value.

Syntax

Attr* createAttribute( DOMString nspuri,
                          DOMString qname,
                          DOMSring value);

Parameter	Description
nspuri	element's namespace URI
qname	qualified name of attribute
value	value of attribute

createCDATASection()

Description

Creates a new CDATA node with the given contents, and returns a pointer to that node.

Syntax

CDATASection* createCDATASection(  DOMString data);

Parameter	Description
data	Contents of node.

createComment()

Description

Creates a new comment node with given contents, and returns a pointer to that node.

Syntax

Comment* createComment(  DOMString data);

Parameter	Description
data	contents of node

createDocumentFragment()

Description

Creates a new document fragment node and returns a pointer to that node.

Syntax

DocumentFragment* createDocumentFragment();

createElement()

Description

Creates a new element node with the given tag name and returns a pointer to that node.

Syntax

Element* createElement(  DOMString tagName);

Parameter	Description
tagName	element's tag name

createElementNS()

Description

Creates a new element node with the given (tag) name and namespace information, and returns a pointer to that node.

Syntax

Element* createElementNS( DOMString nspuri,
                          DOMSring qname);

Parameter	Description
nspuri	element's namespace URI
qname	element's qualified name

createEntityReference()

Description

Creates a new entity reference node and returns a pointer to that node.

Syntax

EntityReference* createEntityReference(  DOMString name);

Parameter	Description
name	name of entity to reference

createProcessingInstruction()

Description

Creates a new processing instruction node and returns a pointer to that node.

Syntax

ProcessingInstruction* createProcessingInstruction( DOMString target,
                                                    DOMString data);

Parameter	Description
data	data for node
target	target part of PI

createTextNode()

Description

Creates a new TEXT node and returns a pointer to that node.

Syntax

Text* createTextNode(  DOMString data);

Parameter	Description
data	data for node

getElementByID()

Description

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

Syntax

Element* getElementByID(  DOMString name);

Parameter	Description
name	element ID

getElementsByTagName()

Description

Returns a NodeList of all the Elements with a given tag name in the order in which they would be encountered in a preorder traversal of the Document tree. If elem is NULL, the entire document is searched. The special value "*" matches all tags. If no matches are found, returns NULL. The options are described in the following table.

Syntax	Description
NodeList* getElementsByTagName( Element *elem, DOMString tagname);	Matches Element by tag name.
NodeList* getElementsByTagNameNS( Element *elem, DOMString nspuri, DOMString local);	Matches Element by tag name and namespace information.

Parameter	Description
elem	root node
tagname	tag name to select
nspuri	namespace URI
local	namespace local name

getImplementation()

Description

Returns the DOMImplementation structure. This function is currently not in use, and is reserved for future DOM implementations.

Syntax

DOMImplementation* getImplementation();

importNode()

Description

Imports a node from another document to this document, and returns a pointer to that node. The returned node has no parent; its value 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 is 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 SOM 2.0 spec for specific action taken for each node type.

Syntax

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

Parameter	Description
ctx	XML context.
deep	Recursively import subtree - TRUE or FALSE.
import	Node to be imported.

saveString()

Description

Allocates memory and saves the given string, returning a pointer to that string. Used to store locally generated strings.

Syntax

DOMString saveString(  DOMString str);

Parameter	Description
str	string to save

---

DocumentType Class

---

Description of DocumentType

This class contains methods for accessing information about the Document Type Definition (DTD) of a document.

---

Methods of DocumentType

Table 16-4 Summary of Methods of DocumentType

Method	Description
getName()	Returns name of DTD.
getEntities()	Returns NamedNodeMap of DTD's (general) entities.
getNotations()	Returns NamedNodeMap of DTD's notations.

getName()

Description

Returns name of DTD.

Syntax

DOMString getName();

getEntities()

Description

Returns map of DTD's (general) entities.

Syntax

NamedNodeMap* getEntities();

getNotations()

Description

Returns map of DTD's notations.

Syntax

NamedNodeMap* getNotations();

---

DOMImplementation Class

---

Description of DOMImplementation

This class contains methods relating to the specific DOM implementation supported by the parser.

---

Methods of DOMImplementation

Table 16-5 Summary of Methods of DOMImplementation

Method	Description
createDocument()	Creates and returns a DOCUMENT node.
createDocumentType()	Creates and returns a DOCUMENT_TYPE (DTD) node.
hasFeature()	Tests if the DOMImplementation implements a specific feature.

createDocument()

Description

Creates a DOCUMENT node and returns a pointer to that node. When DTD is not NULL, its Node.ownerDocument attribute is set to the document being created.

Syntax

Document *createDocument( DOMString uri,
                          DOMString qname,
                          DocumentType *dtd);

Parameter	Description
dtd	document type (DTD)
qname	qualified name of the new document element
uri	namespace URI of the new document element

createDocumentType()

Description

Creates a DOCUMENT_TYPE (DTD) node and returns a pointer to that node.

Syntax

DocumentType *createDocumentType( DOMString qname,
                                  DOMString pubid,
                                  DOMString sysid);

Parameter	Description
pubid	external subset system identifier
qname	qualified name of the new document element
sysid	external subset system identifier

hasFeature()

Description

Tests if the DOM implementation implements a specific feature. Returns TRUE if the feature is supported, FALSE otherwise.

Syntax

boolean hasFeature( DOMString feature,
                    DOMString version);

Parameter	Description
feature	The package name of the feature to test. In Level 1, the legal values are "HTML" and "XML" (case-insensitive)
version	This is the version number of the package name to test. In 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.

---

Element Class

---

Description of Element

This class contains methods pertaining to element nodes.

---

Methods of Element

Table 16-6 Summary of Methods of Element  

Method	Description
getAttribute()	Selects an attribute given its name
getAttributeNode()	Removes an attribute given its name
getElementsByTagName()	Returns a list of element nodes with the given tag name
getElementsByTagNameNS()	Returns a list of element nodes with the given tag name, namespace aware
getTagName()	Returns the node's tag name
initialize()	Initializes a new element node
normalize()	Normalizes an element (merge adjacent text nodes)
removeAttribute()	Removes an attribute given its name
removeAttributeNode()	Removes an attribute node
setAttribute()	Creates a new attribute given its name and value
setAttributeNode()	Adds a new attribute node

getAttribute()

Description

Returns "value" (definition) of named attribute.

Syntax

DOMString getAttribute(  DOMString name);

Parameter	Description
name	name of attribute

getAttributeNode()

Description

Returns pointer to named attribute, or NONE if not found.

Syntax

Attr* getAttributeNode(  DOMString name);

Parameter	Description
name	name of attribute

getElementsByTagName()

Description

Creates and returns a list of matching elements.

Syntax

NodeList* getElementsByTagName( DOMString name);

Parameter	Description
name	tag name to match, "*" for all.

getElementsByTagNameNS()

Description

Creates and returns a list of matching elements, namespace aware.

Syntax

NodeList* getElementsByTagNameNS( DOMString nspuri,
                                  DOMString local);

Parameter	Description
local	Local name to match, "*" for all.
nspuri	Namespace URI.

getTagName()

Description

Returns the tag name of the element. 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 DOM Working Group considers it worthwhile to support both, given the different constituencies the DOM API must satisfy.

Syntax

DOMString getTagName();

initialize()

Description

Initializes a newly allocated element node. Returns 0 on success, or an error code on failure.

Syntax

uword initialize( Document *doc,
                  DOMString nspuri,
                  DOMString qname);

Parameter	Description
doc	XML document.
nspuri	Namespace URI.
qname	Qualified name.

normalize()

Description

Normalizes an element; merge all adjacent TEXT nodes.

Syntax

void normalize();

removeAttribute()

Description

Removes the named attribute.

Syntax

void removeAttribute(  DOMString name);

Parameter	Description
name	name of attribute to remove

removeAttributeNode()

Description

Removes the named attribute node and passes it back.

Syntax

Attr* removeAttributeNode(  Attr* oldAttr);

Parameter	Description
name	attribute to remove

setAttribute()

Description

Creates a new attribute. Returns a pointer to the newly created attribute.

Syntax

Attr* setAttribute( DOMString name,
                    DOMString value);

Parameter	Description
name	name of new attribute
value	value of new attribute

setAttributeNode()

Description

Sets (adds) new attribute node.

Syntax

boolean setAttributeNode( Attr* newAttr,
                          Attr** oldAttr);

Parameter	Description
newAttr	pointer to a new attribute
oldAttr	returned pointer to replaced attribute

---

Entity Class

---

Description of Entity

This class implements the ENTITY node type, a subclass of Node.

---

Methods of Entity

Table 16-7 Summary of Methods of Entity

Method	Description
getNotationName()	Returns entity's NDATA (notation name).
getPublicId()	Returns entity's public ID.
getSystemId()	Returns entity's system ID.

getNotationName()

Description

Returns an entity node's notation name (NDATA).

Syntax

DOMString* getNotationName();

getPublicId()

Description

Returns an entity node's public ID.

Syntax

DOMString getPublicId();

getSystemId()

Description

Returns an entity node's system ID.

Syntax

DOMString getSystemId();

---

EntityReference Class

---

Description of EntityReference

This class implements the ENTITY_REFERENCE node type, a subclass of Node.

---

NamedNodeMap Class

---

Desciption of NamedNodeMap

This class contains methods for accessing the number of nodes in a node map and fetching individual nodes.

---

Methods of NamedNodeMap

Table 16-8 Summary of Methods of NamedNodeMap

Method	Description
free()	Frees the named node map.
getLength()	Returns number of nodes in map.
getNamedItem()	Selects a node by name.
item()	Returns nth node in map.
removeNamedItem()	Removes the named node from map.
setNamedItem()	Sets a node into the map.

free()

Description

Frees the named node map.

Syntax

void free();

getLength()

Description

Returns number of nodes in map.

Syntax

size_t getLength();

getNamedItem()

Description

Selects the node with the given name from the map. Returns NULL if not found.

Syntax

Node* getNamedItem(  String name);

Parameter	Description
name	Name of node to select

item()

Description

Returns a pointer to the nth node in node map.

Syntax

Node* item(  size_t index);

Parameter	Description
size_t	index; zero-based node number

removeNamedItem()

Description

Removes the node with the given name from the node map. Returns a pointer to removed node, NULL if not found.

Syntax

Node* removeNamedItem(  String name);

Parameter	Description
name	name of node to remove

setNamedItem()

Description

Adds a node to the map, replacing any node that already exists with the same name.

Syntax

boolean setNamedItem( Node *node,
                      Node **old);

Parameter	Description
node	Name of node to add
old	Pointer to replaced node, NULL if node is new

---

Node Class

---

Description of Node

This class contains methods for details about a document node

---

Methods of Node

Table 16-9 Summary of Methods of Node  

Method	Description
appendChild()	Appends a new child to the end of the current node's list of children.
cloneNode()	Clones an existing node and optionally all its children.
getAttributes()	Returns structure contains all defined node attributes.
getChildNode()	Returns specific indexed child of given node.
getChildNodes()	Returns structure contains all child nodes of given node.
getContext()	Gets node's context.
getFirstChild()	Returns first child of given node.
getLastChild()	Returns last child of given node.
getLocal()	Returns the local name of the node.
getName()	Returns name of node.
getNamespace()	Returns a node's namespace.
getNextSibling()	Returns a node's next sibling.
getOwnerDocument()	Returns document node which contains a node.
getParentNode()	Returns parent node of given node.
getPrefix()	Returns the namespace prefix for the node.
getPreviousSibling()	Returns the previous sibling of the current node.
getQualifiedName()	Returns namespace qualified node of given node.
getType()	Returns numeric type-code of node.
getValue()	Returns "value" (data) of node.
hasAttributes()	Determines if node has any defined attributes.
hasChildNodes()	Determines if node has children.
insertBefore()	Inserts new child node into a node's list of children.
numChildNodes()	Returns count of number of child nodes of given node.
print()	Formats XML document to stream or buffer.
printSize()	Determines size of formatted XML document (without outputting).
removeChild()	Removes a node from the current node's list of children.
replaceChild()	Replaces a child node with another.
setValue()	Sets a node's value (data).

appendChild()

Description

Appends a new child to the current node's list of children and returns a pointer to that node.

Syntax

Node* appendChild(  Node *newChild);

Parameter	Description
newChild	new child node

cloneNode()

Description

Returns a duplicate of this node; serves as a generic copy constructor for nodes. Returns a pointer to new clone. 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.

Syntax

Node* cloneNode(  boolean deep);

Parameter	Description
deep	recursion flag

getAttributes()

Description

Retrieves structure of all attributes for node. Returns a pointer to structure describing all attributes for node, or NULL if no attributes are defined

Syntax

NamedNodeMap* getAttributes();

getChildNode()

Description

Returns one of the node's children as a pointer to child of node found through the index.

Syntax

Node* getChildNode(  uword index);

Parameter	Description
index	child number, starting at 0

getChildNodes()

Description

Returns node's children as a pointer to structure describing all the node's children.

Syntax

NodeList* getChildNodes();

getContext()

Description

Returns the node's context

Syntax

xmlctx* getContext();

getFirstChild()

Description

Returns a pointer to the node's first child.

Syntax

Node* getFirstChild();

getLastChild()

Description

Returns a pointer to the node's last child.

Syntax

Node* getLastChild();

getLocal()

Description

Returns the node's local name

Syntax

DOMString getLocal();

getName()

Description

Returns name of node, or NULL if the node has no name.

Syntax

DOMString getName();

getNamespace()

Description

Returns the node's namespace; may be NULL.

Syntax

DOMString getNamespace();

getNextSibling()

Description

Returns the next sibling of the node; or the next child of the node's parent. NULL returned if the current child is the last.

Syntax

Node* getNextSibling();

getOwnerDocument()

Description

Returns document node which contains the current node, as a pointer to that document node.

Syntax

Document* getOwnerDocument();

getParentNode()

Description

Returns node's parent.

Syntax

Node* getParentNode();

getPrefix()

Description

Returns the namespace prefix of node; may be NULL.

Syntax

DOMString getPrefix();

getPreviousSibling()

Description

Returns the previous sibling of the node, or the previous child of the node's parent. NULL returned if the current child is the first.

Syntax

Node* getPreviousSibling();

getQualifiedName()

Description

Returns the fully qualified (namespace) name of node.

Syntax

DOMString getQualifiedName();

getType()

Description

Return numeric type code for the node. The possible codes are:

DOCUMENT_FRAGMENT_NODE	ENTITY_NODE
ELEMENT_NODE	PROCESSING_INSTRUCTION_NODE
NOTATION_NODE	COMMENT_NODE
ATTRIBUTE_NODE	DOCUMENT_NODE
TEXT_NODE	DOCUMENT_TYPE_NODE
ENTITY_REFERENCE_NODE	CDATA_SECTION_NODE

Syntax

short getType();

getValue()

Description

Returns "value" (data) of node, or NULL if the node has no value.

Syntax

DOMString getValue();

hasAttributes()

Description

Determines if node has any defined attributes. Returns TRUE if node has attributes, FALSE otherwise.

Syntax

boolean hasAttributes();

hasChildNodes()

Description

Determines if node has any children; returns TRUE if node has children, FALSE otherwise.

Syntax

boolean hasChildNodes();

insertBefore()

Description

Inserts a new child node into the list of children of a parent, before the reference node; the pointer to the new child passed back. If the reference node passed in NULL, appends the new node to the end.

Syntax

Node* insertBefore( Node *newChild,
                    Node *refChild);

Parameter	Description
newChild	new node to insert
refChild	reference node; new node comes before

numChildNodes()

Description

Returns count of node's children; may be 0.

Syntax

uword numChildNodes();

print()

Description

Formats XML document to stream or buffer. The options are described in the following table.

Syntax	Description
void print( File *out = stdout, uword level = 0, uwoard step = 4);	Creates a new parser object.
void print( DOMString buffer, size_t buffsize, uword level = 0, uword step =4);	Creates a new parser object with a given id.

Parameter	Description
out	stdio output stream
level	starting indentation level
step	spaces for each indentation level
buffer	destination buffer
bufsize	size of destination buffer

printSize()

Description

Returns size (in bytes) of formatted XML document, without actually outputting it. Useful for determining final size of document for buffer allocation purposes. Caution, this call is almost as expensive as really outputting the document.

Syntax

size_t printSize( uword level = 0,
                  uwoard step = 4);

Parameter	Description
level	starting indentation level
step	spaces for each indentation level

removeChild()

Description

Removes a child node from the current node's list of children, and passes back the removed child.

Syntax

Node* removeChild();

replaceChild()

Description

Replaces one node with another. newChild replaces oldChild in the list of children in oldChild's parent. oldChild is passed back.

Syntax

Node* replaceChild( Node *newChild,
                    Node *oldChild);

Parameter	Description
newChild	new replacement node
oldChild	old node being replaced

setValue()

Description

Sets a node's "value" (data).

Syntax

void setValue(DOMString data);

Parameter	Description
data	new data for the node

---

NodeList Class

---

Description of NodeList

This class contains methods for extracting nodes from a NodeList.

---

Methods of NodeList

Table 16-10 Summary of Methods of NodeList

Method	Description
free()	Returns number of nodes in list.
getLength()	Returns nth node in list.
item()	Frees the node list.

free()

Description

Frees the node list.

Syntax

void free();

getLength()

Description

Returns number of nodes in list.

Syntax

size_t getLength();

item()

Description

Returns nth node in node list.

Syntax

Node* item( size_t index);

Parameter	Description
index	0-based node number.

---

Notation Class

---

Description of Notation

This class implements the NOTATION node type, a subclass of Node.

---

Methods of Notation

Table 16-11 Summary of Methods of Notation

Method	Description
getData()	Returns notation's data.
getTarget()	Returns notation's target.
setData()	Sets notation's data.

getData()

Description

Returns a notation's data.

Syntax

DOMString getData();

getTarget()

Description

Returns a notation's target.

Syntax

DOMString getTarget();

setData()

Description

Sets a notation's data.

Syntax

void setData(  DOMString data);

Parameter	Description
data	new data

---

ProcessingInstruction Class

---

Description of ProcessingInstruction

This class implements a subclass of Node, PROCESSING_INSTRUCTION node type.

---

Methods of ProcessingInstruction

Table 16-12 Summary of Methods of ProcessingInstruction

Method	Description
getData()()	Returns the PI's data.
getTarget()	Returns the PI's target.
setData()	Sets the PI's data.

getData()

Description

Returns data for a processing instruction.

Syntax

DOMString getData();

getTarget()

Description

Returns a processing instruction's target value.

Syntax

DOMString getTarget();

setData()

Description

Sets the data for a processing instruction.

Syntax

void setData(DOMString data);

Parameter	Description
data	PI's new data

---

Text Class

---

Description of Text

This class contains methods for accessing and modifying the data associated with Text nodes, a subclasses of CharacterData.

---

Methods of Text

splitText()

Description

Gets data (value) of text node. Splits a text node in two. The original node retains its data up to the split point, and the remaining data is turned into a new text node which becomes the next node after. Returns a pointer to the new text node.

Syntax

Text* splitText( unsigned long offset);

Parameter	Description
offset	split point

---

XMLParser Class

---

Description of XMLParser

This class contains top-level methods for invoking the parser and returning high-level information about a document.

---

Methods of XMLParser

Table 16-13 Summary of Methods of XMLParser  

Methods	Description
context()	Retrieves the context.
createDocument()	Creates a Document node and returns a pointer to that node.
getContent()	Returns the content model for a node.
getDocType()	Returns a pointer to a "DocType" structure which describes the DTD
getDocument()	Returns a pointer to the root node of the document after a document has been successfully parsed.
getDocumentElement()	Returns a pointer to the root element (node) of the document after a document has been successfully parsed.
getEncoding()	Returns the name of the current document's character encoding scheme, such as "ASCII", "UTF8", and so on.
isSingleChar()	Returns TRUE if the document is specified as standalone on the <?xml?> line, FALSE otherwise
isStandalone()	Sets the I/O callback functions for the given access method.
setAccess()	Validates the document.
validate()	Frees any memory used during the previous parse.
xmlclean()	Initialize XML parser.
xmlinit()	Initializes encoded XML parser.
xmlinitenc()	Parses a document.
xmlparse()	Parses a buffer.
xmlparseBuffer()	Parses a DTD.
xmlparseDTD()	Parses a document from a file.
xmlparseFile()	Parses a document from a file.
xmlparseStream()	Returns error location information.
xmlwhere()	Retrieves the context.
xmlterm()	Creates a Document node and returns a pointer to that node.

context()

Description

Retrieves the context.

Syntax

xmlctx* context();

createDocument()

Description

Creates a Document node and returns a pointer to that node. When DTD is not NULL, the Node.ownerDocument attribute is set to the document being created.

Syntax

Document* createDocument( DOMString uri,
                          DOMString qname,
                          DocumentType* dtd);

Parameter	Description
uri	namespace URI of the new document element
qname	qualified name of the new document element
dtd	document type (DTD)

getContent()

Description

Returns the content model for a node. Content model nodes are Nodes and can be traversed and examined with the same functions as the parsed document.

Syntax

Node* getContent(Node *node);

Parameter	Description
node	node whose content model to return

getDocType()

Description

Returns a pointer to a "DocType" structure which describes the DTD

Syntax

DocumentType* getDocType();

getDocument()

Description

Returns a pointer to the root node of the document after a document has been successfully parsed. Compare with getDocumentElement which returns the root element node.

Syntax

Node* getDocument();

getDocumentElement()

Description

Returns a pointer to the root element (node) of the document after a document has been successfully parsed.

Syntax

Element* getDocumentElement();

getEncoding()

Description

Returns the name of the current document's character encoding scheme, such as "ASCII", "UTF8", and so on. Compare to isSingleChar flag that only tells whether encoding is single or multibyte.

Syntax

DOMString getEncoding();

isSingleChar()

Description

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

Syntax

boolean isSingleChar();

isStandalone()

Description

Returns TRUE if the document is specified as standalone on the <?xml?> line, FALSE otherwise

Syntax

boolean isStandalone();

setAccess()

Description

Sets the I/O callback functions for the given access method. Returns the error code, or 0 on success.

Most methods have built-in callback functions, so none are provided by the user. The notable exception is XMLACCESS_STREAM, user-defined streams, where the user must set the stream callback functions.

The three callback functions are invoked to open, close, and read from the input source. The functions should be 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 *) or 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 source, if known; if not known, set to 0
parts	(IN)	path broken down into components; opaque pointer
path	(IN)	full path to the source 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)	input handle union

XML-READF is the reader function; it reads data from an open source into a buffer, and returns the number of bytes read.

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

Parameter	IN / OUT	Description
ctx	(IN)	XML context
ih	(IN)	input handle union
dest	(OUT)	destination buffer into which data is read
destsize	(IN)	size of dest
path	(IN)	full path to the source to be opened; only provided here for use in error messages
nraw	(OUT)	number of bytes read
eoi	(OUT)	hit End of Information? Should be set to TRUE or FALSE after each read.

Syntax

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

Parameter	Description
ctx	the XML context
access	access method enum, XMLACCESS_xxx
openf	open-input callback function
closef	close-input callback function
readf	Read-input callback function

validate()

Description

Validates the document. Returns error code, 0 on success.

Syntax

uword validate( Node* root);

Parameter	Description
root	document node to validate

xmlclean()

Description

Frees any memory used during the previous parse. 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. To access only one document's data at a time, within a single context, call xmlclean() before each new parse.

Syntax

void xmlclean();

xmlinit()

Description

Initialize XML parser. Returns error code, 0 on success.

Syntax

uword xmlinit( DOMString incoding, 
               void (*msghdlr)(void *msgctx, DOMString msg, ub4 errcode),
               void *msgctx,
               lpxsaxcb *saxcb,
               void *saxcbctx,
               DOMString lang);

Parameter	Description
incoding	Default input file encoding; UTF8 if not specified
msghdlr	Error message callback
msg	Message
errcode	Error code
msgctx	User-defined ocntext pointer passed to msghdr
saxcb	SAX callback structure (only if using SAX)
saxcbctx	User-defined SAX content structure passed to SAX callback functions
lang	Language of error message; currently not in use

xmlinitenc()

Description

Initializes encoded XML parser. Returns error code, 0 on success.

Syntax

uword xmlinitenc( DOMString incoding,
                  DOMString outcoding, 
                  void (*msghdlr)(void *msgctx, DOMString msg, ub4 errcode),
                  void *msgctx,
                  lpxsaxcb *saxcb,
                  void *saxcbctx,
                  DOMString *lang);

Parameter	Description
incoding	Default input file encoding; UTF8 if not specified
outcoding	Output (DOM) encoding for document data; same as first input, if not specified
msghdlr	Error message callback
msgctx	User-defined pointer passed to msghdr
msg	Message
errcode	Error code
saxcb	SAX callback structure (only if using SAX)
saxcbctx	User-defined SAX content structure passed to SAX callback functions
lang	Language of error message; currently not in use

xmlparse()

Description

Parses a document. Returns error code, 0 on success.

Syntax

uword xmlparse( DOMString doc,
                DOMString encoding,
                ub4 flags);

Parameter	Description
doc	document path
encoding	document's encoding
flags	mask of 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, such as 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.

xmlparseBuffer()

Description

Parses a buffer. Returns error code, 0 on success.

Syntax

uword xmlparseBuffer( DOMString buffer,
                      size_t len, 
                      DOMString encoding, 
                      ub4 flags);

Parameter	Description
buffer	buffer containing document to parse
len	length of document
encoding	document's encoding
flags	mask of 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, such as 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

Parses a DTD. Returns error code, 0 on success.

Syntax

uword xmlparseDTD( DOMString uri,
                   DOMString name,
                   DOMString encoding,
                   ub4 flags);

Parameter	Description
uri	URI pointing to DTD
name	DTD name
encoding	DTD's encoding
flags	Mast of 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, such as 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

Parses a document from a file. Returns error code, 0 on success.

Syntax

uword xmlparseFile( DOMString path,
                    size_t len,
                    DOMString encoding,
                    ub4 flags);

Parameter	Description
path	document path
len	unused parameter
encoding	document's encoding
flags	mask of 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, such as 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

Parses a document from a file. Returns error code, 0 on success.

Syntax

uword xmlparseStream( DOMString path,
                      void *stream,
                      DOMString encoding,
                      ub4 flags);

Parameter	Description
path	unused parameter
stream	input stream
encoding	document's encoding
flags	mask of 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, such as end-of-line, and son 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.

xmlwhere()

Description

Returns error location information. Should only be called from within user error calback function, while error is current.

Syntax

boolean xmlwhere( ub4 *line,
                  DOMString *path,
                  uword idx);

Parameter	Description
line	returned line # where error occurred
path	returned path/URL where error occurred
idx	position in error stack, starting at 0

xmlterm()

Description

Terminates XML parser; tear down and free memory.

Syntax

void xmlterm();

---

C++ SAX APIs

---

Description of C++ SAX API

The SAX API is based on callbacks. Instead of the entire document being parsed and turned into a data structure which may be referenced (by the DOM interface), the SAX interface is serial. As the document is processed, appropriate SAX user callback functions are invoked. Each callback function returns an error code, zero meaning success, any nonzero value meaning failure. If a nonzero code is returned, document processing is stopped.

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.

Note this SAX functionality is identical to the C version.

---

SAX Callback Structure

typedef struct  {
sword (*startDocument) (void *ctx);
sword (*endoocument) (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 *public 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); 
} xmlsaxcb;

---

Methods of C++ SAX API

Table 16-14 Summary of Methods of C++ SAX API  

Method	Description
startDocument()	Starts document processing; called only once.
endDocument()	Finishes document processing; called only once.
startElement()	Starts processing a new document element; called only once for each element.
endElement()	Finishes processing a document element; called only once for each element.
characters()	Processes literal text; called for each piece of literal text.
ignorableWhitespace()	Processes ignorable (non-significant) whitespace; called for each piece of ignorable whitespace.
processingInstruction()	Processes PIs (Processing Instructions); called once for each PI.
notationDecl	Processes notation; called once for each NOTATION.
unparsedEntityDecl()	Processes unparsed entity declarations; called once for each unparsed entity declaration.
nsStartElement()	Starts processing a new document element when the element uses an explicit namespace; called only once for each element.
comment()	Receives notification about an XML source comment.
elementDecl()	Receives notification about an element declaration.
attributeDecl()	Receives notification about an element's attribute declaration.

startDocument()

Description

Starts document processing; called only once. Returns 0 for success or a numeric error code.

Syntax

sword startDocument( void *ctx);

Parameter	Description
ctx	User-defined context as passed to initialize().

endDocument()

Description

Finishes document processing; called only once. Returns 0 for success or a numeric error code.

Syntax

sword endDocument( void *ctx);

Parameter	Description
ctx	User-defined context as passed to initialize().

startElement()

Description

Starts processing a new document element; called only once for each element. Returns 0 for success or a numeric error code.

Syntax

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

Parameter	Description
ctx	User-defined context as passed to initialize().
name	name of node
attrs	array of node's attributes

endElement()

Description

Finishes processing a document element; called only once for each element. Returns 0 for success or a numeric error code.

Syntax

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

Parameter	Description
ctx	User-defined context as passed to initialize().
name	name of node

characters()

Description

Processes literal text; called for each piece of literal text. Returns 0 for success or a numeric error code.

Syntax

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

Parameter	Description
ctx	User-defined context as passed to initialize()
ch	pointer to text
len	number of characters in text

ignorableWhitespace()

Description

Processes ignorable (non-significant) whitespace; called for each piece of ignorable whitespace. Returns 0 for success or a numeric error code.

Syntax

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

Parameter	Description
ctx	User-defined context as passed to initialize()
ch	pointer to whitespace text
len	number of characters in whitespace text

processingInstruction()

Description

Processes PIs (Processing Instructions); called once for each PI. Returns 0 for success or a numeric error code.

Syntax

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

Parameter	Description
ctx	User-defined context as passed to initialize()
data	PI data
target	PI target

notationDecl

Description

Processes notation; called once for each NOTATION. Returns 0 for success or a numeric error code.

Syntax

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

Parameter	Description
ctx	User-defined context as passed to initialize().
name	name of notation
publicId	Public ID
systemID	System ID

unparsedEntityDecl()

Description

Processes unparsed entity declarations; called once for each unparsed entity declaration. Returns 0 for success or a numeric error code.

Syntax

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

Parameter	Description
ctx	User-defined context as passed to initialize()
name	name of entity
publicId	Public ID
systemID	System ID
notationName	notation name

nsStartElement()

Description

Starts processing a new document element when the element uses an explicit namespace; called only once for each element. Returns 0 for success or a numeric error code.

Syntax

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

Parameter	Description
ctx	User-defined context as passed to initialize()
qname	qualified namespac
local	element local name
namespace	element namespace
attrs	specified or default attributes

comment()

Description

Receives notification about an XML source comment. Returns 0 for success or a numeric error code.

Syntax

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

Parameter	Description
ctx	User-defined context as passed to initialize()
ldata	body of comment

a elementDecl( void*, oratext*, oratext*)

elementDecl()

Description

Receives notification about an element declaration. Returns 0 for success or a numeric error code.

Syntax

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

Parameter	Description
ctx	User-defined context as passed to initialize()
name	name of element being declared
content	content model for element

attributeDecl()

Description

Receives notification about an element's attribute declaration. Returns 0 for success or a numeric error code.

Syntax

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

Parameter	Description
ctx	User-defined context as passed to initialize()
elem	name of element for which the attribute is declared
attr	name of attribute declared
body	body of attribute declaration

---

C++ DOM API's

Table 16-15 Classes of C++ DOM API

Class	Superclass
Attribute	Node
CDATASection	Text
CharacterData	Node
Comment	CharacterData
Document	Node
DocumentFragment	Node
DocumentType	Node
Element	Node
Entity	Node
EntityReference	Node
Notation	Node
ProcessingInstruction	Node
Text	CharacterData