Skip Headers

Oracle9i XML API Reference - XDK and Oracle XML DB
Release 2 (9.2)

Part Number A96616-01
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback

Go to previous page Go to next page

16
XML Parser for C++

This chapter contains the following sections:


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


Go to previous page Go to next page
Oracle
Copyright © 2001, 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback