Skip Headers
Oracle® Database XML C API Reference
10g Release 2 (10.2)

Part Number B16207-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

3 Package DOM APIs for C

This implementation follows REC-DOM-Level-1-19981001. Because the DOM standard is object-oriented, some changes were made for C language adaptation.

This chapter contains the following sections:


Attr Interface

Table 3-1 summarizes the methods of available through the Attr interface.

Table 3-1 Summary of Attr Methods; DOM Package

Function Summary
XmlDomGetAttrLocal()
Returns an attribute's namespace local name as NULL-terminated string.
XmlDomGetAttrLocalLen()
Returns an attribute's namespace local name as length-encoded string.
XmlDomGetAttrName()
Return attribute's name as NULL-terminated string.
XmlDomGetAttrNameLen()
Return attribute's name as length-encoded string.
XmlDomGetAttrPrefix()
Returns an attribute's namespace prefix.
XmlDomGetAttrSpecified()
Return flag that indicates whether an attribute was explicitly created.
XmlDomGetAttrURI()
Returns an attribute's namespace URI as NULL-terminated string.
XmlDomGetAttrURILen()
Returns an attribute's namespace URI as length-encoded string.
XmlDomGetAttrValue()
Return attribute's value as NULL-terminated string.
XmlDomGetAttrValueLen()
Return attribute's value as length-encoded string.
XmlDomGetAttrValueStream()
Get attribute value stream-style,i.e.chunked.
XmlDomGetOwnerElem()
Return an attribute's "owning" element.
XmlDomSetAttrValue()
Set an attribute's value.
XmlDomSetAttrValueStream()
Sets an attribute value stream style (chunked).


XmlDomGetAttrLocal()

Returns an attribute's namespace local name (in the data encoding). If the attribute's name is not fully qualified (has no prefix), then the local name is the same as the name.

A length-encoded version is available as XmlDomGetAttrURILen which returns the local name as a pointer and length, for use if the data is known to use XMLType backing store.

Syntax

oratext* XmlDomGetAttrLocal(
   xmlctx *xctx, 
   xmlattrnode *attr);
Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node

Returns

(oratext *) attribute's local name [data encoding]


XmlDomGetAttrLocalLen()

Returns an attribute's namespace local name (in the data encoding). If the attribute's name is not fully qualified (has no prefix), then the local name is the same as the name.

A NULL-terminated version is available as XmlDomGetAttrLocal which returns the local name as NULL-terminated string. If the backing store is known to be XMLType, then the attribute's data will be stored internally as length-encoded. Using the length-based GetXXX functions will avoid having to copy and NULL-terminate the data.

If both the input buffer is non-NULL and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.

Syntax

oratext* XmlDomGetAttrLocalLen(
   xmlctx *xctx, 
   xmlattrnode *attr, 
   oratext *buf, 
   ub4 buflen, 
   ub4 *len);
Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node
buf
IN
input buffer; optional
buflen
IN
input buffer length; optional
len
OUT
length of local name, in characters

Returns

(oratext *) Attr's local name [data encoding]


XmlDomGetAttrName()

Returns the fully-qualified name of an attribute (in the data encoding) as a NULL-terminated string, for example bar\0 or foo:bar\0.

A length-encoded version is available as XmlDomGetAttrNameLen which returns the attribute name as a pointer and length, for use if the data is known to use XMLType backing store.

Syntax

oratext* XmlDomGetAttrName(
   xmlctx *xctx, 
   xmlattrnode *attr);
Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node

Returns

(oratext *) name of attribute [data encoding]


XmlDomGetAttrNameLen()

Returns the fully-qualified name of an attribute (in the data encoding) as a length-encoded string, for example ("bar", 3) or ("foo:bar", 7).

A NULL-terminated version is available as XmlDomGetAttrName which returns the attribute name as NULL-terminated string. If the backing store is known to be XMLType, then the attribute's data will be stored internally as length-encoded. Using the length-based GetXXX() functions will avoid having to copy and NULL-terminate the data.

If both the input buffer is non-NULL and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.

Syntax

oratext* XmlDomGetAttrNameLen(
   xmlctx *xctx, 
   xmlattrnode *attr, 
   oratext *buf, 
   ub4 buflen, 
   ub4 *len);
Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node
buf
IN
input buffer; optional
buflen
IN
input buffer length; optional
len
OUT
length of local name, in characters

Returns

(oratext *) name of attribute [data encoding]


XmlDomGetAttrPrefix()

Returns an attribute's namespace prefix (in the data encoding). If the attribute's name is not fully qualified (has no prefix), NULL is returned.

Syntax

oratext* XmlDomGetAttrPrefix(
   xmlctx *xctx, 
   xmlattrnode *attr);
Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node

Returns

(oratext *) attribute's namespace prefix [data encoding] or NULL


XmlDomGetAttrSpecified()

Return the 'specified' flag for an attribute. If the attribute was explicitly given a value in the original document, this is TRUE; otherwise, it is FALSE. If the node is not an attribute, returns FALSE. If the user sets an attribute's value through DOM, its specified flag will be TRUE. To return an attribute to its default value (if it has one), the attribute should be deleted; it will then be re-created automatically with the default value (and specified will be FALSE).

Syntax

boolean XmlDomGetAttrSpecified(
   xmlctx *xctx,
   xmlattrnode *attr);
Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node

Returns

(boolean) attribute's "specified" flag


XmlDomGetAttrURI()

Returns an attribute's namespace URI (in the data encoding). If the attribute's name is not qualified (does not contain a namespace prefix), it will have the default namespace in effect when the node was created (which may be NULL).

A length-encoded version is available as XmlDomGetAttrURILen which returns the URI as a pointer and length, for use if the data is known to use XMLType backing store.

Syntax

oratext* XmlDomGetAttrURI(
   xmlctx *xctx, 
   xmlattrnode *attr);
Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node

Returns

(oratext *) attribute's namespace URI [data encoding] or NULL


XmlDomGetAttrURILen()

Returns an attribute's namespace URI (in the data encoding) as length-encoded string. If the attribute's name is not qualified (does not contain a namespace prefix), it will have the default namespace in effect when the node was created (which may be NULL).

A NULL-terminated version is available as XmlDomGetAttrURI which returns the URI as NULL-terminated string. If the backing store is known to be XMLType, then the attribute's data will be stored internally as length-encoded. Using the length-based Get functions will avoid having to copy and NULL-terminate the data.

If both the input buffer is non-NULL and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.

Syntax

oratext* XmlDomGetAttrURILen(
   xmlctx *xctx, 
   xmlattrnode *attr, 
   oratext *buf, 
   ub4 buflen, 
   ub4 *len);
Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node
buf
IN
input buffer; optional
buflen
IN
input buffer length; optional
len
OUT
length of URI, in characters

Returns

(oratext *) attribute's namespace URI [data encoding] or NULL


XmlDomGetAttrValue()

Returns the "value" (character data) of an attribute (in the data encoding) as NULL-terminated string. Character and general entities will have been replaced.

A length-encoded version is available as XmlDomGetAttrValueLen which returns the attribute value as a pointer and length, for use if the data is known to use XMLType backing store.

Syntax

oratext* XmlDomGetAttrValue(
   xmlctx *xctx, 
   xmlattrnode *attr);
Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node

Returns

(oratext *) attribute's value


XmlDomGetAttrValueLen()

Returns the "value" (character data) of an attribute (in the data encoding) as length-encoded string. Character and general entities will have been replaced.

A NULL-terminated version is available as XmlDomGetAttrValue which returns the attribute value as NULL-terminated string. If the backing store is known to be XMLType, then the attribute's data will be stored internally as length-encoded. Using the length-based GetXXX() functions will avoid having to copy and NULL-terminate the data.

If both the input buffer is non-NULL and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.

Syntax

oratext* XmlDomGetAttrValueLen(
   xmlctx *xctx,
   xmlattrnode *attr,
   oratext *buf,
   ub4 buflen, 
   ub4 *len);
Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node
buf
IN
input buffer; optional
buflen
IN
input buffer length; optional
len
OUT
length of attribute's value, in characters

Returns

(oratext *) attribute's value


XmlDomGetAttrValueStream()

Returns the large "value" (associated character data) for an attribute and sends it in pieces to the user's output stream. For very large values, it is not always possible to store them [efficiently] as a single contiguous chunk. This function is used to access chunked data of that type.

Syntax

xmlerr XmlDomGetAttrValueStream(
   xmlctx *xctx,
   xmlnode *attr,
   xmlostream *ostream);
Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node
ostream
IN
output stream object

Returns

(xmlerr) numeric error code, 0 on success


XmlDomGetOwnerElem()

Returns the Element node associated with an attribute. Each attr either belongs to an element (one and only one), or is detached and not yet part of the DOM tree. In the former case, the element node is returned; if the attr is unassigned, NULL is returned.

Syntax

xmlelemnode* XmlDomGetOwnerElem(
   xmlctx *xctx,
   xmlattrnode *attr);
Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node

Returns

(xmlelemnode *) attribute's element node [or NULL]


XmlDomSetAttrValue()

Sets the given attribute's value to data. If the node is not an attribute, does nothing. Note that the new value must be in the data encoding! It is not verified, converted, or checked. The attribute's specified flag will be TRUE after setting a new value.

Syntax

void XmlDomSetAttrValue(
   xmlctx *xctx,
   xmlattrnode *attr,
   oratext *value);
Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node
value
IN
new value of attribute; data encoding


XmlDomSetAttrValueStream()

Sets the large "value" (associated character data) for an attribute piecemeal from an input stream. For very large values, it is not always possible to store them efficiently as a single contiguous chunk. This function is used to access chunked data of that type.

Syntax

xmlerr XmlDomSetAttrValueStream(
   xmlctx *xctx,
   xmlnode *attr,
   xmlistream *istream);
Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node
isream
IN
input stream

Returns

(xmlerr) numeric error code, 0 on success


CharacterData Interface

Table 3-2 summarizes the methods of available through the CharacterData interface.

Table 3-2 Summary of CharacterData Method; DOM Package

Function Summary
XmlDomAppendData()
Append data to end of node's current data.
XmlDomDeleteData()
Remove part of node's data.
XmlDomGetCharData()
Return data for node.
XmlDomGetCharDataLength()
Return length of data for node.
XmlDomInsertData()
Insert string into node's current data.
XmlDomReplaceData()
Replace part of node's data.
XmlDomSetCharData()
Set data for node.
XmlDomSubstringData()
Return substring of node's data.


XmlDomAppendData()

Append a string to the end of a CharacterData node's data. If the node is not Text, Comment or CDATA, or if the string to append is NULL, does nothing. The appended data should be in the data encoding. It will not be verified, converted, or checked.

The new node data will be allocated and managed by DOM, but if the previous node value was allocated and manager by the user, they are responsible for freeing it, which is why it is returned.

Syntax

void XmlDomAppendData(
   xmlctx *xctx,
   xmlnode *node,
   oratext *data, 
   oratext **old);
Parameter In/Out Description
xctx
IN
XML context
node
IN
CharacterData node
data
IN
data to append; data encoding
old
OUT
previous data for node; data encoding


XmlDomDeleteData()

Remove a range of characters from a CharacterData node's data. If the node is not text, comment or CDATA, or if the offset is outside of the original data, does nothing. The offset is zero-based, so offset zero refers to the start of the data. Both offset and count are in characters, not bytes. If the sum of offset and count exceeds the data length then all characters from offset to the end of the data are deleted.

The new node data will be allocated and managed by DOM, but if the previous node value was allocated and managed by the user, they are responsible for freeing it, which is why it is returned.

Syntax

void XmlDomDeleteData(
   xmlctx *xctx,
   xmlnode *node,
   ub4 offset, 
   ub4 count,
   oratext **old);
Parameter In/Out Description
xctx
IN
XML context
node
IN
CharacterData node
offset
IN
character offset where to start removing
count
IN
number of characters to delete
old
OUT
previous data for node; data encoding


XmlDomGetCharData()

Returns the data for a CharacterData node (type text, comment or CDATA) in the data encoding. For other node types, or if there is no data, returns NULL.

Syntax

oratext* XmlDomGetCharData(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment or CDATA

Returns

(oratext *) character data of node [data encoding]


XmlDomGetCharDataLength()

Returns the length of the data for a CharacterData node, type Text, Comment or CDATA) in characters, not bytes. For other node types, returns 0.

Syntax

ub4 XmlDomGetCharDataLength(
   xmlctx *xctx,
   xmlnode *cdata);
Parameter In/Out Description
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment or CDATA

Returns

(ub4) length in characters, not bytes, of node's data


XmlDomInsertData()

Insert a string into a CharacterData node's data at the specified position. If the node is not Text, Comment or CDATA, or if the data to be inserted is NULL, or the offset is outside the original data, does nothing. The inserted data must be in the data encoding. It will not be verified, converted, or checked. The offset is specified as characters, not bytes. The offset is zero-based, so inserting at offset zero prepends the data.

The new node data will be allocated and managed by DOM, but if the previous node value was allocated and managed by the user, they are responsible for freeing it (which is why it's returned).

Syntax

void XmlDomInsertData(
   xmlctx *xctx,
   xmlnode *node,
   ub4 offset, 
   oratext *arg,
   oratext **old);
Parameter In/Out Description
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment, or CDATA
offset
IN
character offset where to start inserting
arg
IN
data to insert
old
OUT
previous data for node; data encoding


XmlDomReplaceData()

Replaces a range of characters in a CharacterData node's data with a new string. If the node is not text, comment or CDATA, or if the offset is outside of the original data, or if the replacement string is NULL, does nothing. If the count is zero, acts just as XmlDomInsertData. The offset is zero-based, so offset zero refers to the start of the data. The replacement data must be in the data encoding. It will not be verified, converted, or checked. The offset and count are both in characters, not bytes. If the sum of offset and count exceeds length, then all characters to the end of the data are replaced.

The new node data will be allocated and managed by DOM, but if the previous node value was allocated and managed by the user, they are responsible for freeing it, which is why it is returned.

Syntax

void XmlDomReplaceData(
   xmlctx *xctx,
   xmlnode *node,
   ub4 offset, 
   ub4 count,
   oratext *arg,
   oratext **old);
Parameter In/Out Description
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment, or CDATA
offset
IN
character offset where to start replacing
count
IN
number of characters to replace
arg
IN
replacement substring; data encoding
old
OUT
previous data for node; data encoding


XmlDomSetCharData()

Sets data for a CharacterData node (type text, comment or CDATA), replacing the old data. For other node types, does nothing. The new data is not verified, converted, or checked; it should be in the data encoding.

Syntax

void XmlDomSetCharData(
   xmlctx *xctx,
   xmlnode *node,
   oratext *data);
Parameter In/Out Description
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment, or CDATA
data
IN
new data for node


XmlDomSubstringData()

Returns a range of character data from a CharacterData node, type Text, Comment or CDATA. For other node types, or if count is zero, returns NULL. Since the data is in the data encoding, offset and count are in characters, not bytes. The beginning of the string is offset 0. If the sum of offset and count exceeds the length, then all characters to the end of the data are returned.

The substring is permanently allocated in the node's document's memory pool. To free the substring, use XmlDomFreeString.

Syntax

oratext* XmlDomSubstringData(
   xmlctx *xctx,
   xmlnode *node,
   ub4 offset,
   ub4 count);
Parameter In/Out Description
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment, or CDATA
offset
IN
character offset where to start extraction of substring
count
IN
number of characters to extract

Returns

(oratext *) specified substring.


Document Interface

Table 3-3 summarizes the methods of available through the Document interface.

Table 3-3 Summary of Document Methods; DOM Package

Function Summary
XmlDomCreateAttr()
Create attribute node.
XmlDomCreateAttrNS()
Create attribute node with namespace information.
XmlDomCreateCDATA()
Create CDATA node.
XmlDomCreateComment()
Create comment node.
XmlDomCreateElem()
Create an element node.
XmlDomCreateElemNS()
Create an element node with namespace information.
XmlDomCreateEntityRef()
Create entity reference node.
XmlDomCreateFragment()
Create a document fragment.
XmlDomCreatePI()
Create PI node.
XmlDomCreateText()
Create text node.
XmlDomFreeString()
Frees a string allocate by XmlDomSubstringData, and others.
XmlDomGetBaseURI()
Returns the base URI for a document.
XmlDomGetDTD()
Get DTD for document.
XmlDomGetDecl()
Returns a document's XMLDecl information.
XmlDomGetDocElem()
Get top-level element for document.
XmlDomGetDocElemByID()
Get document element given ID.
XmlDomGetDocElemsByTag()
Obtain document elements.
XmlDomGetDocElemsByTagNS()
Obtain document elements (namespace aware version).
XmlDomGetLastError()
Return last error code for document.
XmlDomGetSchema()
Returns URI of schema associated with document.
XmlDomImportNode()
Import a node from another DOM.
XmlDomIsSchemaBased()
Indicate whether a schema is associated with a document.
XmlDomSaveString()
Saves a string permanently in a document's memory pool.
XmlDomSaveString2()
Saves a Unicode string permanently in a document's memory pool.
XmlDomSetDTD()
Sets DTD for document.
XmlDomSetDocOrder()
Set document order for all nodes.
XmlDomSetLastError()
Sets last error code for document.
XmlDomSync()
Synchronizes the persistent version of a document with its DOM.


XmlDomCreateAttr()

Creates an attribute node with the given name and value (in the data encoding). Note this function differs from the DOM specification, which does not allow the initial value of the attribute to be set (see XmlDomSetAttrValue). The name is required, but the value may be NULL; neither is verified, converted, or checked.

This is the non-namespace aware function (see XmlDomCreateAttrNS): the new attribute will have NULL namespace URI and prefix, and its local name will be the same as its name, even if the name specified is a qualified name.

If given an initial value, the attribute's specified flag will be TRUE.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild, and so on.

See XmlDomSetAttr which creates and adds an attribute in a single operation.

The name and value are not copied, their pointers are just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmlattrnode* XmlDomCreateAttr(
   xmlctx *xctx,
   xmldocnode *doc, 
   oratext *name, 
   oratext *value);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
name
IN
new node's name; data encoding; user control
value
IN
new node's value; data encoding; user control

Returns

(xmlattrnode *) new Attr node.


XmlDomCreateAttrNS()

Creates an attribute node with the given namespace URI and qualified name; this is the namespace-aware version of XmlDomCreateAttr. Note this function differs from the DOM specification, which does not allow the initial value of the attribute to be set (see XmlDomSetAttrValue). The name is required, but the value may be NULL; neither is verified, converted, or checked.

If given an initial value, the attribute's specified flag will be TRUE.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild, and so on. See XmlDomSetAttr which creates and adds an attribute in a single operation.

The URI, qualified name and value are not copied, their pointers are just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmlattrnode* XmlDomCreateAttrNS(
   xmlctx *xctx, 
   xmldocnode *doc, 
   oratext *uri, 
   oratext *qname,
   oratext *value);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
uri
IN
node's namespace URI; data encoding; user control
qname
IN
node's qualified name; data encoding; user control
value
IN
new node's value; data encoding; user control

Returns

(xmlattrnode *) new Attr node.


XmlDomCreateCDATA()

Creates a CDATASection node with the given initial data (which should be in the data encoding). A CDATASection is considered verbatim and is never parsed; it will not be joined with adjacent Text nodes by the normalize operation. The initial data may be NULL; if provided, it is not verified, converted, or checked. The name of a CDATA node is always "#cdata-section".

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild and so on.

The CDATA is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmlcdatanode* XmlDomCreateCDATA(
   xmlctx *xctx, 
   xmldocnode *doc, 
   oratext *data);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
data
IN
new node's CDATA; data encoding; user control

Returns

(xmlcdatanode *) new CDATA node.


XmlDomCreateComment()

Creates a Comment node with the given initial data (which must be in the data encoding). The data may be NULL; if provided, it is not verified, converted, or checked. The name of a Comment node is always "#comment".

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild and so on.

The comment data is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmlcommentnode* XmlDomCreateComment(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *data);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
data
IN
new node's comment; data encoding; user control

Returns

(xmlcommentnode *) new Comment node.


XmlDomCreateElem()

Creates an element node with the given tag name (which should be in the data encoding). Note that the tag name of an element is case sensitive. This is the non-namespace aware function: the new node will have NULL namespace URI and prefix, and its local name will be the same as its tag name, even if the tag name specified is a qualified name.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild and so on.

The tagname is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmlelemnode* XmlDomCreateElem(
   xmlctx *xctx, 
   xmldocnode *doc,
   oratext *tagname);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
tagname
IN
new node's name; data encoding; user control

Returns

(xmlelemnode *) new Element node.


XmlDomCreateElemNS()

Creates an element with the given namespace URI and qualified name. Note that element names are case sensitive, and the qualified name is required though the URI may be NULL. The qualified name will be split into prefix and local parts, retrievable with XmlDomGetNodePrefix, XmlDomGetNodeLocal, and so on; the tagName will be the full qualified name.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild and so on.

The URI and qualified name are not copied, their pointers are just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmlelemnode* XmlDomCreateElemNS(
   xmlctx *xctx,
   xmldocnode *doc, 
   oratext *uri,
   oratext *qname);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
uri
IN
new node's namespace URI; data encoding, user control
qname
IN
new node's qualified name; data encoding; user control

Returns

(xmlelemnode *) new Element node.


XmlDomCreateEntityRef()

Creates an EntityReference node; the name (which should be in the data encoding) is the name of the entity to be referenced. The named entity does not have to exist. The name is not verified, converted, or checked.

EntityReference nodes are never generated by the parser; instead, entity references are expanded as encountered. On output, an entity reference node will turn into a "&name;" style reference.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild, and so on.

The entity reference name is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmlentrefnode* XmlDomCreateEntityRef(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *name);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
name
IN
name of referenced entity; data encoding; user control

Returns

(xmlentrefnode *) new EntityReference node.


XmlDomCreateFragment()

Creates an empty DocumentFragment node. A document fragment is treated specially when it is inserted into a DOM tree: the children of the fragment are inserted in order instead of the fragment node itself. After insertion, the fragment node will still exist, but have no children. See XmlDomInsertBefore, XmlDomReplaceChild, XmlDomAppendChild, and so on. The name of a fragment node is always "#document-fragment".

Syntax

xmlfragnode* XmlDomCreateFragment(
   xmlctx *xctx,
   xmldocnode *doc);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node

Returns

(xmlfragnode *) new empty DocumentFragment node


XmlDomCreatePI()

Creates a ProcessingInstruction node with the given target and data (which should be in the data encoding). The data may be NULL initially, and may be changed later (with XmlDomSetPIData), but the target is required and cannot be changed. Note the target and data are not verified, converted, or checked. The name of a PI node is the same as the target.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild and so on.

The PI's target and data are not copied, their pointers are just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmlpinode* XmlDomCreatePI(
   xmlctx *xctx
   xmldocnode *doc, 
   oratext *target,
   oratext *data);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
target
IN
new node's target; data encoding; user control
data
IN
new node's data; data encoding; user control

Returns

(xmlpinode *) new PI node.


XmlDomCreateText()

Creates a Text node with the given initial data (which must be non-NULL and in the data encoding). The data may be NULL; if provided, it is not verified, converted, checked, or parsed (entities will not be expanded). The name of a fragment node is always "#text". New data for a Text node can be set with XmlDomSetNodeValue; see the CharacterData interface for editing methods.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild and so on.

The text data is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmltextnode* XmlDomCreateText(
   xmlctx *xctx, 
   xmldocnode *doc,
   oratext *data);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
data
IN
new node's text; data encoding; user control

Returns

(xmltextnode *) new Text node.


XmlDomFreeString()

Frees the string allocated by XmlDomSubstringData or similar functions. Note that strings explicitly saved with XmlDomSaveString are not freeable individually.

Syntax

void XmlDomFreeString(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *str);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
document where the string belongs
str
IN
string to free


XmlDomGetBaseURI()

Returns the base URI for a document. Usually only documents that were loaded from a URI will automatically have a base URI; documents loaded from other sources (stdin, buffer, and so on) will not naturally have a base URI, but a base URI may have been set for them using XmlDomSetBaseURI, for the purposes of resolving relative URIs in inclusion.

Syntax

oratext *XmlDomGetBaseURI(
   xmlctx *xctx,
   xmldocnode *doc);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node

Returns

(oratext *) document's base URI [or NULL]


See Also:

XmlDomSetBaseURI()


XmlDomGetDTD()

Returns the DTD node associated with current document; if there is no DTD, returns NULL. The DTD cannot be edited, but its children may be retrieved with XmlDomGetChildNodes as for other node types.

Syntax

xmldtdnode* XmlDomGetDTD(
   xmlctx *xctx,
   xmldocnode *doc);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node

Returns

(xmldtdnode *) DTD node for document [or NULL]


XmlDomGetDecl()

Returns the information from a document's XMLDecl. If there is no XMLDecl, returns XMLERR_NO_DECL. Returned are the XML version# ("1.0" or "2.0"), the specified encoding, and the standalone value. If encoding is not specified, NULL will be set. The standalone flag is three-state: < 0 if standalone was not specified, 0 if it was specified and FALSE, > 0 if it was specified and TRUE.

Syntax

xmlerr XmlDomGetDecl(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext **ver, 
   oratext **enc,
   sb4 *std);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
ver
OUT
XML version
enc
OUT
encoding specification
std
OUT
standalone specification

Returns

(xmlerr) XML error code, perhaps version/encoding/standalone set


XmlDomGetDocElem()

Returns the root element (node) of the DOM tree, or NULL if there is none. Each document has only one uppermost Element node, called the root element. It is created after a document is parsed successfully, or manually by XmlDomCreateElem then XmlDomAppendChild, and so on.

Syntax

xmlelemnode* XmlDomGetDocElem(
   xmlctx *xctx,
   xmldocnode *doc);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node

Returns

(xmlelemnode *) root element [or NULL]


See Also:

XmlDomCreateElem()


XmlDomGetDocElemByID()

Returns the element node which has the given ID. If no such ID is defined, returns NULL. Note that attributes named "ID" are not automatically of type ID; ID attributes (which can have any name) must be declared as type ID in the DTD.

The given ID should be in the data encoding or it might not match.

Syntax

xmlelemnode* XmlDomGetDocElemByID(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *id);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
id
IN
element's unique ID; data encoding

Returns

(xmlelemnode *) matching element.


XmlDomGetDocElemsByTag()

Returns a list of all elements in the document tree rooted at the root node with a given tag name, in document order (the order in which they would be encountered in a preorder traversal of the tree). If root is NULL, the entire document is searched.

The special name "*" matches all tag names; a NULL name matches nothing. Note that tag names are case sensitive, and should be in the data encoding or a mismatch might occur.

This function is not namespace aware; the full tag names are compared. If two qualified names with two different prefixes both of which map to the same URI are compared, the comparison will fail. See XmlDomGetElemsByTagNS for the namespace-aware version.

The list should be freed with XmlDomFreeNodeList when it is no longer needed.

The list is not live, it is a snapshot. That is, if a new node which matched the tag name were added to the DOM after the list was returned, the list would not automatically be updated to include the node.

Syntax

xmlnodelist* XmlDomGetDocElemsByTag(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *name);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
name
IN
tagname to match; data encoding; * for all

Returns

(xmlnodelist *) new NodeList containing all matched Elements.


XmlDomGetDocElemsByTagNS()

Returns a list of all elements (in the document tree rooted at the given node) with a given namespace URI and local name, in the order in which they would be encountered in a preorder traversal of the tree. If root is NULL, the entire document is searched.

The URI and local name should be in the data encoding. The special local name "*" matches all local names; a NULL local name matches nothing. Namespace URIs must always match, however, no wildcard is allowed. Note that comparisons are case sensitive. See XmlDomGetDocElemsByTag for the non-namespace aware version.

The list should be freed with XmlDomFreeNodeList when it is no longer needed.

The list is not live, it is a snapshot. That is, if a new node which matched the tag name were added to the DOM after the list was returned, the list would not automatically be updated to include the node.

Syntax

xmlnodelist* XmlDomGetDocElemsByTagNS(
   xmlctx *xctx,
   xmldocnode *doc, 
   oratext *uri,
   oratext *local);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
uri
IN
namespace URI to match; data encoding; * matches all
local
IN
local name to match; data encoding; * matches all

Returns

(xmlnodelist *) new NodeList containing all matched Elements.


XmlDomGetLastError()

Returns the error code of the last error which occurred in the given document.

Syntax

xmlerr XmlDomGetLastError(
   xmlctx *xctx,
   xmldocnode *doc);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node

Returns

(xmlerr) numeric error code, 0 if no error


XmlDomGetSchema()

Returns URI of schema associated with document, if there is one, else returns NULL. The XmlLoadDom functions take a schema location hint (URI); the schema is used for efficient layout of XMLType data. If a schema was provided at load time, this function returns TRUE.

Syntax

oratext* XmlDomGetSchema(
   xmlctx *xctx,
   xmldocnode *doc);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node

Returns

(oratext *) Schema URI or NULL


XmlDomImportNode()

Imports a node from one Document to another. The new node is an orphan and has no parent; it must be added to the DOM tree with XmlDomAppendChild, and so on. The original node is not modified in any way or removed from its document; instead, a new node is created with copies of all the original node's qualified name, prefix, namespace URI, and local name.

As with XmlDomCloneNode, the deep controls whether the children of the node are recursively imported. If FALSE, only the node itself is imported, and it will have no children. If TRUE, all descendents of the node will be imported as well, and an entire new subtree created.

Document and DocumentType nodes cannot be imported. Imported attributes will have their specified flags set to TRUE. Elements will have only their specified attributes imported; non-specified (default) attributes are omitted. New default attributes (for the destination document) are then added.

Syntax

xmlnode* XmlDomImportNode(
   xmlctx *xctx,
   xmldocnode *doc, 
   xmlctx *nctx,
   xmlnode *node,
   boolean deep);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
nctx
IN
XML context of imported node
node
IN
node to import
deep
IN
TRUE to import the subtree recursively

Returns

(xmlnode *) newly imported node (in this Document).


See Also:

XmlDomCloneNode()


XmlDomIsSchemaBased()

Returns flag specifying whether there is a schema associated with this document. The XmlLoadDom functions take a schema location hint (URI); the schema is used for efficient layout of XMLType data. If a schema was provided at load time, this function returns TRUE.

Syntax

boolean XmlDomIsSchemaBased(
   xmlctx *xctx,
   xmldocnode *doc);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node

Returns

(boolean) TRUE if there is a schema associated with the document


XmlDomSaveString()

Copies the given string into the document's memory pool, so that it persists for the life of the document. The individual string will not be freeable, and the storage will be returned only when the entire document is freed. Works on single-byte or multibyte encodings; for Unicode strings, use XmlDomSaveString2.

Syntax

oratext* XmlDomSaveString(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *str);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
str
IN
string to save; data encoding; single- or multi-byte only

Returns

(oratext *) saved copy of string


XmlDomSaveString2()

Copies the given string into the document's memory pool, so that it persists for the life of the document. The individual string will not be freeable, and the storage will be returned only when the entire document is free. Works on Unicode strings only; for single-byte or multibyte strings, use XmlDomSaveString.

Syntax

ub2* XmlDomSaveString2(
   xmlctx *xctx,
   xmldocnode *doc,
   ub2 *ustr);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
ustr
IN
string to save; data encoding; Unicode only

Returns

(ub2 *) saved copy of string


XmlDomSetBaseURI()

Only documents that were loaded from a URI will automatically have a base URI; documents loaded from other sources (stdin, buffer, and so on) will not naturally have a base URI, so this API is used to set a base URI, for the purposes of relative URI resolution in includes. The base URI should be in the data encoding, and a copy will be made.

Syntax

xmlerr XmlDomSetBaseURI(
   xmlctx *xctx, 
   xmldocnode *doc, 
   oratext *uri);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
uri
IN
base URI to set; data encoding

Returns

(xmlerr) XML error code


See Also:

XmlDomGetBaseURI()


XmlDomSetDTD()

Sets the DTD for document. Note this call may only be used for a blank document, before any parsing has taken place. A single DTD can be set for multiple documents, so when a document with a set DTD is freed, the set DTD is not also freed.

Syntax

xmlerr XmlDomSetDTD(
   xmlctx *xctx, 
   xmldocnode *doc, 
   xmldtdnode *dtdnode);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
dtdnode
IN
DocumentType node to set

Returns

(xmlerr) numeric error code, 0 on success


XmlDomSetDocOrder()

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

Syntax

ub4 XmlDomSetDocOrder(
   xmlctx *xctx, 
   xmldocnode *doc,
   ub4 start_id);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
start_id
IN
string ID number

Returns

(ub4) highest ordinal assigned


XmlDomSetLastError()

Sets the Last Error code for the given document. If doc is NULL, sets the error code for the XML context.

Syntax

xmlerr XmlDomSetLastError(
   xmlctx *xctx, 
   xmldocnode *doc,
   xmlerr errcode);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node
errcode
IN
error code to set, 0 to clear error

Returns

(xmlerr) original error code


XmlDomSync()

Causes a modified DOM to be written back out to its original source, synchronizing the persistent store and in-memory versions.

Syntax

xmlerr XmlDomSync(
   xmlctx *xctx, 
   xmldocnode *doc);
Parameter In/Out Description
xctx
IN
XML context
doc
IN
XML document node

Returns

(xmlerr) numeric error code, 0 on success


DocumentType Interface

Table 3-4 summarizes the methods of available through the DocumentType interface.

Table 3-4 Summary of DocumentType Methods; DOM Package

Function Summary
XmlDomGetDTDEntities()
Get entities of DTD.
XmlDomGetDTDInternalSubset()
Get DTD's internal subset.
XmlDomGetDTDName()
Get name of DTD.
XmlDomGetDTDNotations()
Get notations of DTD.
XmlDomGetDTDPubID()
Get DTD's public ID.
XmlDomGetDTDSysID()
Get DTD's system ID.


XmlDomGetDTDEntities()

Returns a named node map of general entities defined by the DTD. If the node is not a DTD, or has no general entities, returns NULL.

Syntax

xmlnamedmap* XmlDomGetDTDEntities(
   xmlctx *xctx,
   xmldtdnode *dtd);
Parameter In/Out Description
xctx
IN
XML context
dtd
IN
DTD node

Returns

(xmlnamedmap *) named node map containing entities declared in DTD


XmlDomGetDTDInternalSubset()

Returns the content model for an element. If there is no DTD, returns NULL.

Syntax

xmlnode* XmlDomGetDTDInternalSubset(
   xmlctx *xctx,
   xmldtdnode *dtd,
   oratext *name);
Parameter In/Out Description
xctx
IN
XML context
dtd
IN
DTD node
name
IN
name of Element; data encoding

Returns

(xmlnode *) content model subtree


XmlDomGetDTDName()

Returns a DTD's name (specified immediately after the DOCTYPE keyword), or NULL if the node is not type DTD.

Syntax

oratext* XmlDomGetDTDName(
   xmlctx *xctx,
   xmldtdnode *dtd);
Parameter In/Out Description
xctx
IN
XML context
dtd
IN
DTD node

Returns

(oratext *) name of DTD


XmlDomGetDTDNotations()

Returns named node map of notations declared by the DTD. If the node is not a DTD or has no Notations, returns NULL.

Syntax

xmlnamedmap* XmlDomGetDTDNotations(
   xmlctx *xctx,
   xmldtdnode *dtd);
Parameter In/Out Description
xctx
IN
XML context
dtd
IN
DTD node

Returns

(xmlnamedmap *) named node map containing notations declared in DTD


XmlDomGetDTDPubID()

Returns a DTD's public identifier.

Syntax

oratext* XmlDomGetDTDPubID(
   xmlctx *xctx,
   xmldtdnode *dtd);
Parameter In/Out Description
xctx
IN
XML context
dtd
IN
DTD node

Returns

(oratext *) DTD's public identifier [data encoding]


XmlDomGetDTDSysID()

Returns a DTD's system identifier.

Syntax

oratext* XmlDomGetDTDSysID(
   xmlctx *xctx,
   xmldtdnode *dtd);
Parameter In/Out Description
xctx
IN
XML context
dtd
IN
DTD node

Returns

(oratext *) DTD's system identifier [data encoding]


Element Interface

Table 3-5 summarizes the methods of available through the Element Interface.

Table 3-5 Summary of Element Methods; DOM Package

Function Summary
XmlDomGetAttr()
Return attribute's value given its name.
XmlDomGetAttrNS()
Return attribute's value given its URI and local name.
XmlDomGetAttrNode()
Get attribute by name.
XmlDomGetAttrNodeNS()
Get attribute by name (namespace aware version).
XmlDomGetChildrenByTag()
Get children of element with given tag name (non-namespace aware).
XmlDomGetChildrenByTagNS()
Get children of element with tag name (namespace aware version).
XmlDomGetDocElemsByTag()
Obtain doc elements.
XmlDomGetDocElemsByTagNS()
Obtain doc elements (namespace aware version).
XmlDomGetTag()
Return an element node's tag name.
XmlDomHasAttr()
Does named attribute exist?
XmlDomHasAttrNS()
Does named attribute exist (namespace aware version)?
XmlDomRemoveAttr()
Remove attribute with specified name.
XmlDomRemoveAttrNS()
Remove attribute with specified URI and local name.
XmlDomRemoveAttrNode()
Remove attribute node.
XmlDomSetAttr()
Set new attribute for element.
XmlDomSetAttrNS()
Set new attribute for element (namespace aware version).
XmlDomSetAttrNode()
Set attribute node.
XmlDomSetAttrNodeNS()
Set attribute node (namespace aware version).


XmlDomGetAttr()

Returns the value of an element's attribute (specified by name). Note that an attribute may have the empty string as its value, but cannot be NULL. If the element does not have an attribute with the given name, NULL is returned.

Syntax

oratext* XmlDomGetAttr(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
name
IN
attribute's name

Returns

(oratext *) named attribute's value [data encoding; may be NULL]


XmlDomGetAttrNS()

Returns the value of an element's attribute (specified by URI and local name). Note that an attribute may have the empty string as its value, but cannot be NULL. If the element does not have an attribute with the given name, NULL is returned.

Syntax

oratext* XmlDomGetAttrNS(
   xmlctx *xctx,
   xmlelemnode *elem, 
   oratext *uri,
   oratext *local);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
uri
IN
attribute's namespace URI; data encoding
local
IN
attribute's local name; data encoding

Returns

(oratext *) named attribute's value [data encoding; may be NULL]


XmlDomGetAttrNode()

Returns an element's attribute specified by name. If the node is not an element or the named attribute does not exist, returns NULL.

Syntax

xmlattrnode* XmlDomGetAttrNode(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
name
IN
attribute's name; data encoding

Returns

(xmlattrnode *) attribute with the specified name [or NULL]


XmlDomGetAttrNodeNS()

Returns an element's attribute specified by URI and localname. If the node is not an element or the named attribute does not exist, returns NULL.

Syntax

xmlattrnode* XmlDomGetAttrNodeNS(
   xmlctx *xctx,
   xmlelemnode *elem, 
   oratext *uri,
   oratext *local);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
uri
IN
attribute's namespace URI; data encoding
local
IN
attribute's local name; data encoding

Returns

(xmlattrnode *) attribute node with the given URI/local name [or NULL]


XmlDomGetChildrenByTag()

Returns a list of children of an element with the given tag name, in the order in which they would be encountered in a preorder traversal of the tree. The tag name should be in the data encoding. The special name "*" matches all tag names; a NULL name matches nothing. Note that tag names are case sensitive. This function is not namespace aware; the full tag names are compared. If two prefixes which map to the same URI are compared, the comparison will fail. See XmlDomGetChildrenByTagNS for the namespace-aware version. The returned list can be freed with XmlDomFreeNodeList.

Syntax

xmlnodelist* XmlDomGetChildrenByTag(
   xmlctx *xctx, 
   xmlelemnode *elem,
   oratext *name);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
name
IN
tag name to match; data encoding; * for all

Returns

(xmlnodelist *) node list of matching children


XmlDomGetChildrenByTagNS()

Returns a list of children of an element with the given URI and local name, in the order in which they would be encountered in a preorder traversal of the tree. The URI and local name should be in the data encoding. The special name "*" matches all URIs or tag names; a NULL name matches nothing. Note that names are case sensitive. See XmlDomGetChildrenByTag for the non-namespace version. The returned list can be freed with XmlDomFreeNodeList.

Syntax

xmlnodelist* XmlDomGetChildrenByTagNS(
   xmlctx *xctx,
   xmlelemnode *elem, 
   oratext *uri,
   oratext *local);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
uri
IN
namespace URI to match; data encoding; * matches all
local
IN
local name to match; data encoding; * matches all

Returns

(xmlnodelist *) node list of matching children


XmlDomGetElemsByTag()

Returns a list of all elements (in the document tree rooted at the root node) with a given tag name, in the order in which they would be encountered in a preorder traversal of the tree. If root is NULL, the entire document is searched. The tag name should be in the data encoding. The special name "*" matches all tag names; a NULL name matches nothing. Note that tag names are case sensitive. This function is not namespace aware; the full tag names are compared. If two prefixes which map to the same URI are compared, the comparison will fail. See XmlDomGetElemsByTagNS for the namespace-aware version. The returned list can be freed with XmlDomFreeNodeList.

Syntax

xmlnodelist* XmlDomGetElemsByTag(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
name
IN
tag name to match; data encoding; * for all

Returns

(xmlnodelist *) node list of matching elements


XmlDomGetElemsByTagNS()

Returns a list of all elements (in the document tree rooted at the root node) with a given URI and localname, in the order in which they would be encountered in a preorder traversal of the tree. If root is NULL, the entire document is searched. The tag name should be in the data encoding. The special name "**" matches all tag names; a NULL name matches nothing. Note that tag names are case sensitive. This function is not namespace aware; the full tag names are compared. If two prefixes which map to the same URI are compared, the comparison will fail. The returned list can be freed with XmlDomFreeNodeList.

Syntax

xmlnodelist* XmlDomGetElemsByTagNS(
   xmlctx *xctx,
   xmlelemnode *elem, 
   oratext *uri,
   oratext *local);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
uri
IN
namespace URI to match; data encoding; * for all
local
IN
local name to match; data encoding; * for all

Returns

(xmlnodelist *) node list of matching elements


XmlDomGetTag()

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

Syntax

oratext* XmlDomGetTag(
   xmlctx *xctx,
   xmlelemnode *elem);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
Element node

Returns

(oratext *) element's name [data encoding]


XmlDomHasAttr()

Determines if an element has an attribute with the given name. Returns TRUE if so, FALSE if not.

Syntax

boolean XmlDomHasAttr(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
Element node
name
IN
attribute's name; data encoding

Returns

(boolean) TRUE if element has attribute with given name


See Also:

XmlDomHasAttrNS()


XmlDomHasAttrNS()

Determines if an element has an attribute with the given URI and localname. Returns TRUE if so, FALSE if not.

Syntax

boolean XmlDomHasAttrNS(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *uri,
   oratext *local);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
Element node
uri
IN
attribute's namespace URI; data encoding
local
IN
attribute's local name; data encoding

Returns

(boolean) TRUE if element has attribute with given URI/localname


See Also:

XmlDomHasAttr()


XmlDomRemoveAttr()

Removes an attribute (specified by name). If the removed attribute has a default value it is immediately re-created with that default. Note that the attribute is removed from the element's list of attributes, but the attribute node itself is not destroyed.

Syntax

void XmlDomRemoveAttr(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
name
IN
attribute's name; data encoding


XmlDomRemoveAttrNS()

Removes an attribute (specified by URI and local name). If the removed attribute has a default value it is immediately re-created with that default. Note that the attribute is removed from the element's list of attributes, but the attribute node itself is not destroyed.

Syntax

void XmlDomRemoveAttrNS(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *uri,
   oratext *local);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
uri
IN
attribute's namespace URI
local
IN
attribute's local name


XmlDomRemoveAttrNode()

Removes an attribute from an element. If the attribute has a default value, it is immediately re-created with that value (Specified set to FALSE). Returns the removed attribute on success, else NULL.

Syntax

xmlattrnode* XmlDomRemoveAttrNode(
   xmlctx *xctx,
   xmlelemnode *elem,
   xmlattrnode *oldAttr);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
oldAtrr
IN
attribute node to remove

Returns

(xmlattrnode *) replaced attribute node [or NULL]


See Also:

XmlDomRemoveAttr()


XmlDomSetAttr()

Creates a new attribute for an element with the given name and value (which should be in the data encoding). If the named attribute already exists, its value is simply replaced. The name and value are not verified, converted, or checked. The value is not parsed, so entity references will not be expanded. The attribute's specified flag will be set.

Syntax

void XmlDomSetAttr(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name,
   oratext *value);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
name
IN
attribute's name; data encoding
value
IN
attribute's value; data encoding


XmlDomSetAttrNS()

Creates a new attribute for an element with the given URI, localname and value (which should be in the data encoding). If the named attribute already exists, its value is simply replaced. The name and value are not verified, converted, or checked.

The value is not parsed, so entity references will not be expanded.

The attribute's specified flag will be set.

Syntax

void XmlDomSetAttrNS(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *uri, 
   oratext *qname,
   oratext *value);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
uri
IN
attribute's namespace URI; data encoding
qname
IN
attribute's qualified name; data encoding
value
IN
attribute's value; data encoding


XmlDomSetAttrNode()

Adds a new attribute to an element. If an attribute with the given name already exists, it is replaced and the old attribute returned through oldNode. If the attribute is new, it is added to the element's list and oldNode set to NULL.

Syntax

xmlattrnode* XmlDomSetAttrNode(
   xmlctx *xctx,
   xmlelemnode *elem,
   xmlattrnode *newAttr);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
newAttr
IN
attribute node to add

Returns

(xmlattrnode *) replaced attribute node (or NULL)


XmlDomSetAttrNodeNS()

Adds a new attribute to an element. If an attribute with newNode's URI and localname already exists, it is replaced and the old attribute returned through oldNode. If the attribute is new, it is added to the element's list and oldNode set to NULL.

Syntax

xmlattrnode* XmlDomSetAttrNodeNS(
   xmlctx *xctx,
   xmlelemnode *elem,
   xmlattrnode *newAttr);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
element node
newAttr
IN
attribute node to add

Returns

(xmlattrnode *) replaced attribute node [or NULL]


Entity Interface

Table 3-6 summarizes the methods of available through the Entity interface.

Table 3-6 Summary of Entity Methods; DOM Package

Function Summary
XmlDomGetEntityNotation()
Get entity's notation.
XmlDomGetEntityPubID()
Get entity's public ID.
XmlDomGetEntitySysID()
Get entity's system ID.
XmlDomGetEntityType()
Get entity's type.


XmlDomGetEntityNotation()

For unparsed entities, returns the name of its notation (in the data encoding). For parsed entities and other node types, returns NULL.

Syntax

oratext* XmlDomGetEntityNotation(
   xmlctx *xctx,
   xmlentnode *ent);
Parameter In/Out Description
xctx
IN
XML context
ent
IN
entity node

Returns

(oratext *) entity's notation [data encoding; may be NULL]


XmlDomGetEntityPubID()

Returns an entity's public identifier (in the data encoding). If the node is not an entity, or has no defined public ID, returns NULL.

Syntax

oratext* XmlDomGetEntityPubID(
   xmlctx *xctx,
   xmlentnode *ent);
Parameter In/Out Description
xctx
IN
XML context
ent
IN
entity node

Returns

(oratext *) entity's public identifier [data encoding; may be NULL]


XmlDomGetEntitySysID()

Returns an entity's system identifier (in the data encoding). If the node is not an entity, or has no defined system ID, returns NULL.

Syntax

oratext* XmlDomGetEntitySysID(
   xmlctx *xctx, 
   xmlentnode *ent);
Parameter In/Out Description
xctx
IN
XML context
ent
IN
entity node

Returns

(oratext *) entity's system identifier [data encoding; may be NULL]


XmlDomGetEntityType()

Returns a boolean for an entity describing whether it is general (TRUE) or parameter (FALSE).

Syntax

boolean XmlDomGetEntityType(
   xmlctx *xctx,
   xmlentnode *ent);
Parameter In/Out Description
xctx
IN
XML context
ent
IN
entity node

Returns

(boolean) TRUE for general entity, FALSE for parameter entity


NamedNodeMap Interface

Table 3-7 summarizes the methods of available through the NamedNodeMap interface.

Table 3-7 Summary of NamedNodeMap Methods; DOM Package

Function Summary
XmlDomGetNamedItem()
Return named node from list.
XmlDomGetNamedItemNS()
Return named node from list (namespace aware version).
XmlDomGetNodeMapItem()
Return nth node in list.
XmlDomGetNodeMapLength()
Return length of named node map.
XmlDomRemoveNamedItem()
Remove node from named node map.
XmlDomRemoveNamedItemNS()
Remove node from named node map (namespace aware version).
XmlDomSetNamedItem()
Set node in named node list.
XmlDomSetNamedItemNS()
Set node in named node list (namespace aware version).


XmlDomGetNamedItem()

Retrieves an item from a NamedNodeMap, specified by name (which should be in the data encoding). This is a non-namespace-aware function; it just matches (case sensitively) on the whole qualified name. Note this function differs from the DOM spec in that the index of the matching item is also returned.

Syntax

xmlnode* XmlDomGetNamedItem(
   xmlctx *xctx,
   xmlnamedmap *map,
   oratext *name);
Parameter In/Out Description
xctx
IN
XML context
map
IN
NamedNodeMap
name
IN
name of the node to retrieve

Returns

(xmlnode *) Node with the specified name [or NULL]


XmlDomGetNamedItemNS()

Retrieves an item from a NamedNodeMap, specified by URI and localname (which should be in the data encoding). Note this function differs from the DOM spec in that the index of the matching item is also returned.

Syntax

xmlnode* XmlDomGetNamedItemNS(
   xmlctx *xctx,
   xmlnamedmap *map, 
   oratext *uri,
   oratext *local);
Parameter In/Out Description
xctx
IN
XML context
map
IN
NamedNodeMap
uri
IN
namespace URI of the node to retrieve; data encoding
local
IN
local name of the node to retrieve; data encoding

Returns

(xmlnode *) node with given local name and namespace URI [or NULL]


XmlDomGetNodeMapItem()

Retrieves an item from a NamedNodeMap, specified by name (which should be in the data encoding). This is a non-namespace-aware function; it just matches (case sensitively) on the whole qualified name. Note this function differs from the DOM specification in that the index of the matching item is also returned. Named "item" in W3C specification.

Syntax

xmlnode* XmlDomGetNodeMapItem(
   xmlctx *xctx, 
   xmlnamedmap *map, 
   ub4 index);
Parameter In/Out Description
xctx
IN
XML context
map
IN
NamedNodeMap
index
IN
0-based index for the map

Returns

(xmlnode *) node at the nth position in the map (or NULL)


XmlDomGetNodeMapLength()

Returns the number of nodes in a NamedNodeMap (the length). Note that nodes are referred to by index, and the range of valid indexes is 0 through length-1.

Syntax

ub4 XmlDomGetNodeMapLength(
   xmlctx *xctx,
   xmlnamedmap *map);
Parameter In/Out Description
xctx
IN
XML context
map
IN
NamedNodeMap

Returns

(ub4) number of nodes in NamedNodeMap


XmlDomRemoveNamedItem()

Removes a node from a NamedNodeMap, specified by name. This is a non-namespace-aware function; it just matches (case sensitively) on the whole qualified name. If the removed node is an attribute with default value (not specified), it is immediately replaced. The removed node is returned; if no removal took place, NULL is returned.

Syntax

xmlnode* XmlDomRemoveNamedItem(
   xmlctx *xctx,
   xmlnamedmap *map,
   oratext *name);
Parameter In/Out Description
xctx
IN
XML context
map
IN
NamedNodeMap
name
IN
name of node to remove

Returns

(xmlnode *) node removed from this map


XmlDomRemoveNamedItemNS()

Removes a node from a NamedNodeMap, specified by URI and localname. If the removed node is an attribute with default value (not specified), it is immediately replaced. The removed node is returned; if no removal took place, NULL is returned.

Syntax

xmlnode* XmlDomRemoveNamedItemNS(
   xmlctx *xctx,
   xmlnamedmap *map, 
   oratext *uri,
   oratext *local);
Parameter In/Out Description
xctx
IN
XML context
map
IN
NamedNodeMap
uri
IN
namespace URI of the node to remove; data encoding
local
IN
local name of the node to remove; data encoding

Returns

(xmlnode *) node removed from this map


XmlDomSetNamedItem()

Adds a new node to a NamedNodeMap. If a node already exists with the given name, replaces the old node and returns it. If no such named node exists, adds the new node to the map and sets old to NULL. This is a non-namespace-aware function; it just matches (case sensitively) on the whole qualified name. Since some node types have fixed names (Text, Comment, and so on), trying to set another of the same type will always cause replacement.

Syntax

xmlnode* XmlDomSetNamedItem(
   xmlctx *xctx,
   xmlnamedmap *map,
   xmlnode *newNode);
Parameter In/Out Description
xctx
IN
XML context
map
IN
NamedNodeMap
newNode
IN
new node to store in map

Returns

(xmlnode *) the replaced node (or NULL)


XmlDomSetNamedItemNS()

Adds a new node to a NamedNodeMap. If a node already exists with the given URI and localname, replaces the old node and returns it. If no such named node exists, adds the new node to the map and sets old to NULL. Since some node types have fixed names (Text, Comment, and so on), trying to set another of the same type will always cause replacement.

Syntax

xmlnode* XmlDomSetNamedItemNS(
   xmlctx *xctx, 
   xmlnamedmap *map, 
   xmlnode *newNode);
Parameter In/Out Description
xctx
IN
XML context
map
IN
NamedNodeMap
newNode
IN
new node to store in map

Returns

(xmlnode *) replaced Node [or NULL]


Node Interface

Table 3-8 summarizes the methods of available through the Node interface.

Table 3-8 Summary of Text Methods; DOM Package

Function Summary
XmlDomAppendChild()
Append new child to node's list of children.
XmlDomCleanNode()
Clean a node (free DOM allocations).
XmlDomCloneNode()
Clone a node.
XmlDomFreeNode()
Free a node allocated with XmlDomCreateXXX.
XmlDomGetAttrs()
Return attributes of node.
XmlDomGetChildNodes()
Return children of node.
XmlDomGetDefaultNS()
Get default namespace for node.
XmlDomGetFirstChild()
Returns first child of node.
XmlDomGetFirstPfnsPair()
Get first prefix namespace pair.
XmlDomGetLastChild()
Returns last child of node.
XmlDomGetNextPfnsPair()
Get subsequent prefix namespace pair.
XmlDomGetNextSibling()
Return next sibling of node.
XmlDomGetNodeLocal()
Get local part of node's qualified name as NULL-terminated string.
XmlDomGetNodeLocalLen()
Get local part of node's qualified name as length-encoded string.
XmlDomGetNodeName()
Get node's name as NULL-terminated string.
XmlDomGetNodeNameLen()
Get node's name as length-encoded string.
XmlDomGetNodePrefix()
Return namespace prefix of node.
XmlDomGetNodeType()
Get node's numeric type code.
XmlDomGetNodeURI()
Return namespace URI of node as a NULL-terminated string.
XmlDomGetNodeURILen()
Return namespace URI of node as length-encoded string.
XmlDomGetNodeValue()
Get node's value as NULL-terminated string.
XmlDomGetNodeValueLen()
Get node value as length-encoded string.
XmlDomGetNodeValueStream()
Get node value stream-style (chunked).
XmlDomGetOwnerDocument()
Get the owner document of node.
XmlDomGetParentNode()
Get parent node.
XmlDomGetPrevSibling()
Return previous sibling of node.
XmlDomGetSourceEntity()
Return the entity node if the input file is an external entity.
XmlDomGetSourceLine()
Return source line number of node.
XmlDomGetSourceLocation()
Return source location (path, URI, and so on) of node.
XmlDomHasAttr()
Does named attribute exist?
XmlDomHasChildNodes()
Test if node has children.
XmlDomInsertBefore()
Insert new child in to node's list of children.
XmlDomNormalize()
Normalize a node by merging adjacent text nodes.
XmlDomNumAttrs()
Return number of attributes of element.
XmlDomNumChildNodes()
Return number of children of node.
XmlDomPrefixToURI()
Get namespace URI for prefix.
XmlDomRemoveChild()
Remove an existing child node.
XmlDomReplaceChild()
Replace an existing child of a node.
XmlDomSetDefaultNS()
Set default namespace for node.
XmlDomSetNodePrefix()
Set namespace prefix of node.
XmlDomSetNodeValue()
Set node value.
XmlDomSetNodeValueLen()
Set node value as length-encoded string.
XmlDomSetNodeValueStream()
Set node value stream-style (chunked).
XmlDomValidate()
Validate a node against current DTD.


XmlDomAppendChild()

Appends the node to the end of the parent's list of children and returns the new node. If newChild is a DocumentFragment, all of its children are appended in original order; the DocumentFragment node itself is not.

Syntax

xmlnode* XmlDomAppendChild(
   xmlctx *xctx, 
   xmlnode *parent, 
   xmlnode *newChild);
Parameter In/Out Description
xctx
IN
XML context
parent
IN
parent to receive a new node
newChild
IN
node to add

Returns

(xmlnode *) node added


XmlDomCleanNode()

Frees parts of the node which were allocated by DOM itself, but does not recurse to children or touch the node's attributes. After freeing part of the node (such as name), a DOM call to get that part (such as XmlDomGetNodeName) should return a NULL pointer. Used to manage the allocations of a node parts of which are controlled by DOM, and part by the user. Calling clean frees all allocations may by DOM and leaves the user's allocations alone. The user is responsible for freeing their own allocations.

Syntax

void XmlDomCleanNode(
   xmlctx *xctx, 
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
node to clean


See Also:

XmlDomFreeNode()


XmlDomCloneNode()

Creates and returns a duplicate of a node. The duplicate node has no parent. Cloning an element copies all attributes and their values, including those generated by the XML processor to represent defaulted attributes, but it 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 the node. Note that a clone of an unspecified attribute node is specified. If deep is TRUE, all children of the node are recursively cloned, and the cloned node will have cloned children; a non-deep clone will have no children.

Syntax

xmlnode* XmlDomCloneNode(
   xmlctx *xctx, 
   xmlnode *node, 
   boolean deep);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node
deep
IN
TRUE to recursively clone children

Returns

(xmlnode *) duplicate (cloned) node


See Also:

XmlDomImportNode()


XmlDomFreeNode()

Free a node allocated with XmlDomCreateXXX. Frees all resources associated with a node, then frees the node itself. Certain parts of the node are under DOM control, and some parts may be under user control. DOM keeps flags tracking who owns what, and only frees its own allocations. The user is responsible for freeing their own parts of the node before calling XmlDomFreeNode.

Syntax

void XmlDomFreeNode(
   xmlctx *xctx, 
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node to free


See Also:

XmlDomCleanNode()


XmlDomGetAttrs()

Returns a NamedNodeMap of attributes of an element node, or NULL if it has no attributes. For other node types, NULL is returned. Note that if an element once had attributes, but they have all been removed, an empty list will be returned. So, presence of the list does not mean the element has attributes. You must check the size of the list with XmlDomNumAttrs or use XmlDomHasChildNodes first.

Syntax

xmlnamedmap* XmlDomGetAttrs(
   xmlctx *xctx, 
   xmlelemnode *elem);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
XML element node

Returns

(xmlnamedmap *) NamedNodeMap of node's attributes


XmlDomGetChildNodes()

Returns a list of the node's children, or NULL if it has no children. Only Element, Document, DTD, and DocumentFragment nodes may have children; all other types will return NULL.

Note that an empty list may be returned if the node once had children, but all have been removed! That is, the list may exist but have no members. So, presence of the list alone does not mean the node has children. You must check the size of the list with XmlDomNumChildNodes or use XmlDomHasChildNodes first.

The xmlnodelist structure is opaque and can only be manipulated with functions in the NodeList interface.

The returned list is live; all changes in the original node are reflected immediately.

Syntax

xmlnodelist* XmlDomGetChildNodes(
   xmlctx *xctx, 
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(xmlnodelist *) live NodeList containing all children of node


XmlDomGetDefaultNS()

Gets the default namespace for a node.

Syntax

oratext* XmlDomGetDefaultNS(
   xmlctx *xctx, 
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
element or attribute DOM node

Returns

(oratext *) default namespace for node [data encoding; may be NULL]


XmlDomGetFirstChild()

Returns the first child of a node, or NULL if the node has no children. Only Element, Document, DTD, and DocumentFragment nodes may have children; all other types will return NULL.

Syntax

xmlnode* XmlDomGetFirstChild(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(xmlnode *) first child of node


XmlDomGetFirstPfnsPair()

This function is to allow implementations an opportunity to speedup the iteration of all available prefix-URI bindings available on a given node. It returns a state structure and the prefix and URI of the first prefix-URI mapping. The state structure should be passed to XmlDomGetNextPfnsPair on the remaining pairs.

Syntax

xmlpfnspair* XmlDomGetFirstPfnsPair(
   xmlctx *xctx, 
   xmlnode *node, 
   oratext **prefix,
   oratext **uri);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node
prefix
OUT
prefix of first mapping; data encoding
uri
OUT
URI of first mapping; data encoding

Returns

(xmlpfnspair *) iterating object or NULL of no prefixes


XmlDomGetLastChild()

Returns the last child of a node, or NULL if the node has no children. Only Element, Document, DTD, and DocumentFragment nodes may have children; all other types will return NULL.

Syntax

xmlnode* XmlDomGetLastChild(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(xmlnode *) last child of node


XmlDomGetNextPfnsPair()

This function is to allow implementations an opportunity to speedup the iteration of all available prefix-URI bindings available on a given node. Given an iterator structure from XmlDomGetFirstPfnsPair, returns the next prefix-URI mapping; repeat calls to XmlDomGetNextPfnsPair until NULL is returned.

Syntax

xmlpfnspair* XmlDomGetNextPfnsPair(
   xmlctx *xctx
   xmlpfnspair *pfns,
   oratext **prefix,
   oratext **uri);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node
prefix
OUT
prefix of next mapping; data encoding
uri
OUT
URI of next mapping; data encoding

Returns

(xmlpfnspair *) iterating object, NULL when no more pairs


XmlDomGetNextSibling()

Returns the node following a node at the same level in the DOM tree. That is, for each child of a parent node, the next sibling of that child is the child which comes after it. If a node is the last child of its parent, or has no parent, NULL is returned.

Syntax

xmlnode* XmlDomGetNextSibling(
   xmlctx *xctx, 
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(xmlnode *) node immediately following node at same level


XmlDomGetNodeLocal()

Returns the namespace local name for a node as a NULL-terminated string. If the node's name is not fully qualified (has no prefix), then the local name is the same as the name.

A length-encoded version is available as XmlDomGetNodeLocalLen which returns the local name as a pointer and length, for use if the data is known to use XMLType backing store.

Syntax

oratext* XmlDomGetNodeLocal(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(oratext *) local name of node [data encoding]


XmlDomGetNodeLocalLen()

Returns the namespace local name for a node as a length-encoded string. If the node's name is not fully qualified (has no prefix), then the local name is the same as the name.

A NULL-terminated version is available as XmlDomGetNodeLocal which returns the local name as NULL-terminated string. If the backing store is known to be XMLType, then the node's data will be stored internally as length-encoded. Using the length-based Get functions will avoid having to copy and NULL-terminate the data.

If both the input buffer is non-NULL and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.

Syntax

oratext* XmlDomGetNodeLocalLen(
   xmlctx *xctx,
   xmlnode *node,
   oratext *buf,
   ub4 buflen, 
   ub4 *len);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node
buf
IN
input buffer; optional
buflen
IN
input buffer length; optional
len
OUT
length of local name, in characters

Returns

(oratext *) local name of node [data encoding]


XmlDomGetNodeName()

Returns the (fully-qualified) name of a node (in the data encoding) as a NULL-terminated string, for example bar\0 or foo:bar\0.

Note that some node types have fixed names: "#text", "#cdata-section", "#comment", "#document", "#document-fragment".

A node's name cannot be changed once it is created, so there is no matching SetNodeName function.

A length-based version is available as XmlDomGetNodeNameLen which returns the node name as a pointer and length, for use if the data is known to use XMLType backing store.

Syntax

oratext* XmlDomGetNodeName(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(oratext *) name of node [data encoding]


XmlDomGetNodeNameLen()

Returns the (fully-qualified) name of a node (in the data encoding) as a length-encoded string, for example "bar", 3 or "foo:bar", 7.

Note that some node types have fixed names: "#text", "#cdata-section", "#comment", "#document", "#document-fragment".

A node's name cannot be changed once it is created, so there is no matching SetNodeName function.

A NULL-terminated version is available as XmlDomGetNodeName which returns the node name as NULL-terminated string. If the backing store is known to be XMLType, then the node's name will be stored internally as length-encoded. Using the length-encoded GetXXX functions will avoid having to copy and NULL-terminate the name.

If both the input buffer is non-NULL and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.

Syntax

oratext* XmlDomGetNodeNameLen(
   xmlctx *xctx,
   xmlnode *node,
   oratext *buf,
   ub4 buflen, 
   ub4 *len);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node
buf
IN
input buffer; optional
buflen
IN
input buffer length; optional
len
OUT
length of name, in characters

Returns

(oratext *) name of node, with length of name set in 'len'


XmlDomGetNodePrefix()

Returns the namespace prefix for a node (as a NULL-terminated string). If the node's name is not fully qualified (has no prefix), NULL is returned.

Syntax

oratext* XmlDomGetNodePrefix(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(oratext *) namespace prefix of node [data encoding; may be NULL]


XmlDomGetNodeType()

Returns the type code of a node. The type names and numeric values match the DOM specification:

Additional Oracle extension node types are as follows:

Syntax

xmlnodetype XmlDomGetNodeType(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(xmlnodetype) numeric type-code of the node


XmlDomGetNodeURI()

Returns the namespace URI for a node (in the data encoding) as a NULL-terminated string. If the node's name is not qualified (does not contain a namespace prefix), it will have the default namespace in effect when the node was created (which may be NULL).

A length-encoded version is available as XmlDomGetNodeURILen which returns the URI as a pointer and length, for use if the data is known to use XMLType backing store.

Syntax

oratext* XmlDomGetNodeURI(
   xmlctx *xctx, 
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(oratext *) namespace URI of node [data encoding; may be NULL]


XmlDomGetNodeURILen()

Returns the namespace URI for a node (in the data encoding) as length-encoded string. If the node's name is not qualified (does not contain a namespace prefix), it will have the default namespace in effect when the node was created (which may be NULL).

A NULL-terminated version is available as XmlDomGetNodeURI which returns the URI value as NULL-terminated string. If the backing store is known to be XMLType, then the node's data will be stored internally as length-encoded. Using the length-based Get functions will avoid having to copy and NULL-terminate the data.

If both the input buffer is non-NULL and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.

Syntax

oratext* XmlDomGetNodeURILen(
   xmlctx *xctx,
   xmlnode *node,
   oratext *buf,
   ub4 buflen, 
   ub4 *len);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node
buf
IN
input buffer; optional
buflen
IN
input buffer length; optional
len
OUT
length of URI, in characters

Returns

(oratext *) namespace URI of node [data encoding; may be NULL]


XmlDomGetNodeValue()

Returns the "value" (associated character data) for a node as a NULL-terminated string. Character and general entities will have been replaced. Only Attr, CDATA, Comment, ProcessingInstruction and Text nodes have values, all other node types have NULL value.

A length-encoded version is available as XmlDomGetNodeValueLen which returns the node value as a pointer and length, for use if the data is known to use XMLType backing store.

Syntax

oratext* XmlDomGetNodeValue(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(oratext *) value of node


XmlDomGetNodeValueLen()

Returns the "value" (associated character data) for a node as a length-encoded string. Character and general entities will have been replaced. Only Attr, CDATA, Comment, PI and Text nodes have values, all other node types have NULL value.

A NULL-terminated version is available as XmlDomGetNodeValue which returns the node value as NULL-terminated string. If the backing store is known to be XMLType, then the node's data will be stored internally as length-encoded. Using the length-based Get functions will avoid having to copy and NULL-terminate the data.

If both the input buffer is non-NULL and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.

Syntax

oratext* XmlDomGetNodeValueLen(
   xmlctx *xctx, 
   xmlnode *node, 
   oratext *buf, 
   ub4 buflen, 
   ub4 *len);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node
buf
IN
input buffer; optional
buflen
IN
input buffer length; optional
len
OUT
length of value, in bytes

Returns

(oratext *) value of node


XmlDomGetNodeValueStream()

Returns the large data for a node and sends it in pieces to the user's output stream. For very large values, it is not always possible to store them [efficiently] as a single contiguous chunk. This function is used to access chunked data of that type. Only XMLType chunks its data (sometimes); XDK's data is always contiguous.

Syntax

xmlerr XmlDomGetNodeValueStream(
   xmlctx *xctx, 
   xmlnode *node, 
   xmlostream *ostream);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node
ostream
IN
output stream object

Returns

(xmlerr) numeric error code, 0 on success


XmlDomGetOwnerDocument()

Returns the Document node associated with a node. Each node may belong to only one document, or may not be associated with any document at all (such as immediately after XmlDomCreateElem, and so on). The "owning" document [node] is returned, or NULL for an orphan node.

Syntax

xmldocnode* XmlDomGetOwnerDocument(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(xmldocnode *) document node is in


XmlDomGetParentNode()

Returns a node's parent node. All nodes types except Attr, Document, DocumentFragment, Entity, and Notation may have a parent (these five exceptions always have a NULL parent). If a node has just been created but not yet added to the DOM tree, or if it has been removed from the DOM tree, its parent is also NULL.

Syntax

xmlnode* XmlDomGetParentNode(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(xmlnode *) parent of node


XmlDomGetPrevSibling()

Returns the node preceding a node at the same level in the DOM tree. That is, for each child of a parent node, the previous sibling of that child is the child which came before it. If a node is the first child of its parent, or has no parent, NULL is returned.

Syntax

xmlnode* XmlDomGetPrevSibling(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(xmlnode *) node immediately preceding node at same level


XmlDomGetSourceEntity()

Returns the external entity node whose inclusion caused the creation of the given node.

Syntax

xmlentnode* XmlDomGetSourceEntity(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(xmlentnode *) entity node if the input is from an external entity


XmlDomGetSourceLine()

Returns the line# in the original source where the node started. The first line in every input is line #1.

Syntax

ub4 XmlDomGetSourceLine(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(ub4) line number of node in original input source


XmlDomGetSourceLocation()

Return source location (path, URI, and so on) of node. Note this will be in the compiler encoding, not the data encoding!

Syntax

oratext* XmlDomGetSourceLocation(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(oratext *) full path of input source [in compiler encoding]


XmlDomHasAttrs()

Test if an element has attributes. Returns TRUE if any attributes of any sort are defined (namespace or regular).

Syntax

boolean XmlDomHasAttrs(
   xmlctx *xctx,
   xmlelemnode *elem);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
XML element node

Returns

(boolean) TRUE if element has attributes


XmlDomHasChildNodes()

Test if a node has children. Only Element, Document, DTD, and DocumentFragment nodes may have children. Note that just because XmlDomGetChildNodes returns a list does not mean the node actually has children, since the list may be empty, so a non-NULL return from XmlDomGetChildNodes should not be used as a test.

Syntax

boolean XmlDomHasChildNodes(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(boolean) TRUE if the node has any children


XmlDomInsertBefore()

Inserts the node newChild before the existing child node refChild in the parent node. If refChild is NULL, appends to parent's children as for each XmlDomAppendChild; otherwise it must be a child of the given parent. If newChild is a DocumentFragment, all of its children are inserted (in the same order) before refChild; the DocumentFragment node itself is not. If newChild is already in the DOM tree, it is first removed from its current position.

Syntax

xmlnode* XmlDomInsertBefore(
   xmlctx *xctx,
   xmlnode *parent, 
   xmlnode *newChild,
   xmlnode *refChild);
Parameter In/Out Description
xctx
IN
XML context
parent
IN
parent that receives a new child
newChild
IN
node to insert
refChild
IN
reference node

Returns

(xmlnode *) node being inserted


XmlDomNormalize()

Normalizes the subtree rooted at an element, merges adjacent Text nodes children of elements. Note that adjacent Text nodes will never be created during a normal parse, only after manipulation of the document with DOM calls.

Syntax

void XmlDomNormalize(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node


XmlDomNumAttrs()

Returns the number of attributes of an element. Note that just because a list is returned by XmlDomGetAttrs does not mean it contains any attributes; it may be an empty list with zero length.

Syntax

ub4 XmlDomNumAttrs(
   xmlctx *xctx,
   xmlelemnode *elem);
Parameter In/Out Description
xctx
IN
XML context
elem
IN
XML element node

Returns

(ub4) number of attributes of node


XmlDomNumChildNodes()

Returns the number of children of a node. Only Element, Document, DTD, and DocumentFragment nodes may have children, all other types return 0. Note that just because XmlDomGetChildNodes returns a list does not mean that it contains any children; it may be an empty list with zero length.

Syntax

ub4 XmlDomNumChildNodes(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node

Returns

(ub4) number of children of node


XmlDomPrefixToURI()

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

Syntax

oratext* XmlDomPrefixToURI(
   xmlctx *xctx,
   xmlnode *node,
   oratext *prefix);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node
prefix
IN
prefix to map

Returns

(oratext *) URI for prefix [data encoding; NULL if no match]


XmlDomRemoveChild()

Removes a node from its parent's list of children and returns it. The node is orphaned; its parent will be NULL after removal.

Syntax

xmlnode* XmlDomRemoveChild(
   xmlctx *xctx, 
   xmlnode *oldChild);
Parameter In/Out Description
xctx
IN
XML context
oldChild
IN
node to remove

Returns

(xmlnode *) node removed


XmlDomReplaceChild()

Replaces the child node oldChild with the new node newChild in oldChild's parent, and returns oldChild (which is now orphaned, with a NULL parent). If newChild is a DocumentFragment, all of its children are inserted in place of oldChild; the DocumentFragment node itself is not. If newChild is already in the DOM tree, it is first removed from its current position.

Syntax

xmlnode* XmlDomReplaceChild(
   xmlctx *xctx, 
   xmlnode *newChild,
   xmlnode *oldChild);
Parameter In/Out Description
xctx
IN
XML context
newChild
IN
new node that is substituted
oldChild
IN
old node that is replaced

Returns

(xmlnode *) node replaced


XmlDomSetDefaultNS()

Set the default namespace for a node

Syntax

void XmlDomSetDefaultNS(
   xmlctx *xctx,
   xmlnode *node,
   oratext *defns);
Parameter In/Out Description
xctx
IN
XML context
node
IN
element or attribute DOM node
defns
IN
new default namespace for the node


XmlDomSetNodePrefix()

Sets the namespace prefix of node (as NULL-terminated string). Does not verify the prefix is defined. Just causes a new qualified name to be formed from the new prefix and the old local name; the new qualified name will be under DOM control and should not be managed by the user.

Syntax

void XmlDomSetNodePrefix(
   xmlctx *xctx,
   xmlnode *node,
   oratext *prefix);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node
prefix
OUT
new namespace prefix


XmlDomSetNodeValue()

Sets a node's value (character data) as a NULL-terminated string. Does not allow setting the value to NULL. Only Attr, CDATA, Comment, PI and Text nodes have values; trying to set the value of another type of node is a no-op. The new value must be in the data encoding. It is not verified, converted, or checked.

The value is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmlerr XmlDomSetNodeValue(
   xmlctx *xctx,
   xmlnode *node,
   oratext *value);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node
value
IN
node's new value; data encoding; user control

Returns

(xmlerr) numeric error code, 0 on success


XmlDomSetNodeValueLen()

Sets the value (associated character data) for a node as a length-encoded string.

A NULL-terminated version is available as XmlDomSetNodeValue which takes the node value as a NULL-terminated string. If the backing store is known to be XMLType, then the node's data will be stored internally as length-encoded. Using the length-based Set functions will avoid having to copy and NULL-terminate the data.

Syntax

xmlerr XmlDomSetNodeValueLen(
   xmlctx *xctx, 
   xmlnode *node, 
   oratext *value, 
   ub4 len);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node
value
IN
node's new value; data encoding; user control
len
IN
length of value, in bytes

Returns

(xmlerr) numeric error code, 0 on success


XmlDomSetNodeValueStream()

Sets the large "value" (character data) for a node piecemeal from an input stream. For very large values, it is not always possible to store them [efficiently] as a single contiguous chunk. This function is used to store chunked data of that type. Used only for XMLType data; XDK's data is always contiguous.

Syntax

xmlerr XmlDomSetNodeValueStream(
   xmlctx *xctx, 
   xmlnode *node,
   xmlistream *istream);
Parameter In/Out Description
xctx
IN
XML context
node
IN
XML node
istream
IN
input stream object

Returns

(xmlerr) numeric error code, 0 on success


XmlDomValidate()

Given a root node, validates it against the current DTD.

Syntax

xmlerr XmlDomValidate(
   xmlctx *xctx,
   xmlnode *node);
Parameter In/Out Description
xctx
IN
XML context
node
IN
node to validate

Returns

(xmlerr) error code, XMLERR_OK [0] means node is valid


NodeList Interface

Table 3-9 summarizes the methods of available through the NodeList interface.

Table 3-9 Summary of NodeList Methods; DOM Package

Function Summary
XmlDomFreeNodeList()
Free a node list returned by XmlDomGetElemsByTag, and so on.
XmlDomGetNodeListItem()
Return nth node in list.
XmlDomGetNodeListLength()
Return length of node list.


XmlDomFreeNodeList()

Free a node list returned by XmlDomGetElemsByTag or related functions, releasing all resources associated with it. If given a node list that is part of the DOM proper (such as the children of a node), does nothing.

Syntax

void XmlDomFreeNodeList(
   xmlctx *xctx,
   xmlnodelist *list);
Parameter In/Out Description
xctx
IN
XML context
list
IN
NodeList to free


XmlDomGetNodeListItem()

Return nth node in a node list. The first item is index 0.

Syntax

xmlnode* XmlDomGetNodeListItem(
   xmlctx *xctx,
   xmlnodelist *list,
   ub4 index);
Parameter In/Out Description
xctx
IN
XML context
list
IN
NodeList
index
IN
index into list

Returns

(xmlnode *) node at the nth position in node list [or NULL]


XmlDomGetNodeListLength()

Returns the number of nodes in a node list (its length). Note that nodes are referred to by index, so the range of valid indexes is 0 through length-1.

Syntax

ub4 XmlDomGetNodeListLength(
   xmlctx *xctx,
   xmlnodelist *list);
Parameter In/Out Description
xctx
IN
XML context
list
IN
NodeList

Returns

(ub4) number of nodes in node list


Notation Interface

Table 3-10 summarizes the methods of available through the Notation interface.

Table 3-10 Summary of NodeList Methods; DOM Package

Function Summary
XmlDomGetNotationPubID()
Get notation's public ID
XmlDomGetNotationSysID()
Get notation's system ID.


XmlDomGetNotationPubID()

Return a notation's public identifier (in the data encoding).

Syntax

oratext* XmlDomGetNotationPubID(
   xmlctx *xctx,
   xmlnotenode *note);
Parameter In/Out Description
xctx
IN
XML context
note
IN
Notation node

Returns

(oratext *) notation's public identifier [data encoding; may be NULL]


XmlDomGetNotationSysID()

Return a notation's system identifier (in the data encoding).

Syntax

oratext* XmlDomGetNotationSysID(
   xmlctx *xctx, 
   xmlnotenode *note);
Parameter In/Out Description
xctx
IN
XML context
note
IN
Notation node

Returns

(oratext *) notation's system identifier [data encoding; may be NULL]


ProcessingInstruction Interface

Table 3-11 summarizes the methods of available through the ProcessingInstruction interface.

Table 3-11 Summary of ProcessingInstruction Methods; DOM Package

Function Summary
XmlDomGetPIData()
Get processing instruction's data.
XmlDomGetPITarget()
Get PI's target.
XmlDomSetPIData()
Set processing instruction's data.


XmlDomGetPIData()

Returns the content (data) of a processing instruction (in the data encoding). If the node is not a ProcessingInstruction, returns NULL. The content is the part from the first non-whitespace character after the target until the ending "?>".

Syntax

oratext* XmlDomGetPIData(
   xmlctx *xctx, 
   xmlpinode *pi);
Parameter In/Out Description
xctx
IN
XML context
pi
IN
ProcessingInstruction node

Returns

(oratext *) processing instruction's data [data encoding]


XmlDomGetPITarget()

Returns a processing instruction's target string. If the node is not a ProcessingInstruction, returns NULL. The target is the first token following the markup that begins the ProcessingInstruction. All ProcessingInstructions must have a target, though the data part is optional.

Syntax

oratext* XmlDomGetPITarget(
   xmlctx *xctx,
   xmlpinode *pi);
Parameter In/Out Description
xctx
IN
XML context
pi
IN
ProcessingInstruction node

Returns

(oratext *) processing instruction's target [data encoding]


XmlDomSetPIData()

Sets a ProcessingInstruction's content, which must be in the data encoding. It is not permitted to set the data to NULL. If the node is not a ProcessingInstruction, does nothing. The new data is not verified, converted, or checked.

Syntax

void XmlDomSetPIData(
   xmlctx *xctx, 
   xmlpinode *pi, 
   oratext *data);
Parameter In/Out Description
xctx
IN
XML context
pi
IN
ProcessingInstruction node
data
IN
ProcessingInstruction's new data; data encoding


Text Interface

Table 3-12 summarizes the methods of available through the Text interface.

Table 3-12 Summary of Text Methods; DOM Package

Function Summary
XmlDomSplitText()
Split text node in to two.


XmlDomSplitText()

Splits a single text node into two text nodes; the original data is split between them. If the given node is not type text, or the offset is outside of the original data, does nothing and returns NULL. The offset is zero-based, and is in characters, not bytes. The original node is retained, its data is just truncated. A new text node is created which contains the remainder of the original data, and is inserted as the next sibling of the original. The new text node is returned.

Syntax

xmltextnode* XmlDomSplitText(
   xmlctx *xctx, 
   xmltextnode *textnode, 
   ub4 offset);
Parameter In/Out Description
xctx
IN
XML context
textnode
IN
Text node
offset
IN
0-based character count at which to split text

Returns

(xmltextnode *) new text node