3 Package DOM APIs for C

Attr Interface

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

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

xctx

IN

attr

IN

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

xctx

IN

attr

IN

buf

IN

buflen

IN

len

OUT

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

xctx

IN

attr

IN

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

xctx

IN

attr

IN

buf

IN

buflen

IN

len

OUT

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

xctx

IN

attr

IN

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

xctx

IN

attr

IN

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

xctx

IN

attr

IN

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

xctx

IN

attr

IN

buf

IN

buflen

IN

len

OUT

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

xctx

IN

attr

IN

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

xctx

IN

attr

IN

buf

IN

buflen

IN

len

OUT

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

xctx

IN

attr

IN

ostream

IN

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

xctx

IN

attr

IN

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

xctx

IN

attr

IN

value

IN

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

xctx

IN

attr

IN

isream

IN

Returns

(xmlerr) numeric error code, 0 on success

CharacterData Interface

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

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

xctx

IN

node

IN

data

IN

old

OUT

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

xctx

IN

node

IN

offset

IN

count

IN

old

OUT

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

xctx

IN

node

IN

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

xctx

IN

node

IN

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

xctx

IN

node

IN

offset

IN

arg

IN

old

OUT

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

xctx

IN

node

IN

offset

IN

count

IN

arg

IN

old

OUT

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

xctx

IN

node

IN

data

IN

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

xctx

IN

node

IN

offset

IN

count

IN

Returns

(oratext *) specified substring.

Document Interface

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

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

xctx

IN

doc

IN

name

IN

value

IN

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

xctx

IN

doc

IN

uri

IN

qname

IN

value

IN

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

xctx

IN

doc

IN

data

IN

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

xctx

IN

doc

IN

data

IN

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

xctx

IN

doc

IN

tagname

IN

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

xctx

IN

doc

IN

uri

IN

qname

IN

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

xctx

IN

doc

IN

name

IN

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

xctx

IN

doc

IN

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

xctx

IN

doc

IN

target

IN

data

IN

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

xctx

IN

doc

IN

data

IN

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

xctx

IN

doc

IN

str

IN

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

xctx

IN

doc

IN

Returns

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

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

xctx

IN

doc

IN

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

xctx

IN

doc

IN

ver

OUT

enc

OUT

std

OUT

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

xctx

IN

doc

IN

Returns

(xmlelemnode *) root element [or NULL]

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

xctx

IN

doc

IN

id

IN

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

xctx

IN

doc

IN

name

IN

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

xctx

IN

doc

IN

uri

IN

local

IN

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

xctx

IN

doc

IN

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

xctx

IN

doc

IN

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

xctx

IN

doc

IN

nctx

IN

node

IN

deep

IN

Returns

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

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

xctx

IN

doc

IN

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

xctx

IN

doc

IN

str

IN

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

xctx

IN

doc

IN

ustr

IN

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

xctx

IN

doc

IN

uri

IN

Returns

(xmlerr) XML error code

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

xctx

IN

doc

IN

dtdnode

IN

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

xctx

IN

doc

IN

start_id

IN

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

xctx

IN

doc

IN

errcode

IN

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

xctx

IN

doc

IN

Returns

(xmlerr) numeric error code, 0 on success

DocumentType Interface

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

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

xctx

IN

dtd

IN

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

xctx

IN

dtd

IN

name

IN

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

xctx

IN

dtd

IN

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

xctx

IN

dtd

IN

Returns

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

XmlDomGetDTDPubID()

Returns a DTD's public identifier.

Syntax

oratext* XmlDomGetDTDPubID(
   xmlctx *xctx,
   xmldtdnode *dtd);

xctx

IN

dtd

IN

Returns

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

XmlDomGetDTDSysID()

Returns a DTD's system identifier.

Syntax

oratext* XmlDomGetDTDSysID(
   xmlctx *xctx,
   xmldtdnode *dtd);

xctx

IN

dtd

IN

Returns

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

Element Interface

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

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

xctx

IN

elem

IN

name

IN

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

xctx

IN

elem

IN

uri

IN

local

IN

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

xctx

IN

elem

IN

name

IN

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

xctx

IN

elem

IN

uri

IN

local

IN

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

xctx

IN

elem

IN

name

IN

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

xctx

IN

elem

IN

uri

IN

local

IN

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

xctx

IN

elem

IN

name

IN

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

xctx

IN

elem

IN

uri

IN

local

IN

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

xctx

IN

elem

IN

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

xctx

IN

elem

IN

name

IN

Returns

(boolean) TRUE if element has attribute with given name

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

xctx

IN

elem

IN

uri

IN

local

IN

Returns

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

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

xctx

IN

elem

IN

name

IN

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

xctx

IN

elem

IN

uri

IN

local

IN

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

xctx

IN

elem

IN

oldAtrr

IN

Returns

(xmlattrnode *) replaced attribute node [or NULL]

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

xctx

IN

elem

IN

name

IN

value

IN

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

xctx

IN

elem

IN

uri

IN

qname

IN

value

IN

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

xctx

IN

elem

IN

newAttr

IN

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

xctx

IN

elem

IN

newAttr

IN

Returns

(xmlattrnode *) replaced attribute node [or NULL]

Entity Interface

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

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

xctx

IN

ent

IN

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

xctx

IN

ent

IN

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

xctx

IN

ent

IN

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

xctx

IN

ent

IN

Returns

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

NamedNodeMap Interface

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

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

xctx

IN

map

IN

name

IN

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

xctx

IN

map

IN

uri

IN

local

IN

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

xctx

IN

map

IN

index

IN

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

xctx

IN

map

IN

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

xctx

IN

map

IN

name

IN

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

xctx

IN

map

IN

uri

IN

local

IN

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

xctx

IN

map

IN

newNode

IN

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

xctx

IN

map

IN

newNode

IN

Returns

(xmlnode *) replaced Node [or NULL]

Node Interface

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

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

xctx

IN

parent

IN

newChild

IN

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

xctx

IN

node

IN

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

xctx

IN

node

IN

deep

IN

Returns

(xmlnode *) duplicate (cloned) node

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

xctx

IN

node

IN

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

xctx

IN

elem

IN

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

xctx

IN

node

IN

Returns

(xmlnodelist *) live NodeList containing all children of node

XmlDomGetDefaultNS()

Gets the default namespace for a node.

Syntax

oratext* XmlDomGetDefaultNS(
   xmlctx *xctx, 
   xmlnode *node);

xctx

IN

node

IN

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

xctx

IN

node

IN

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

xctx

IN

node

IN

prefix

OUT

uri

OUT

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

xctx

IN

node

IN

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

xctx

IN

node

IN

prefix

OUT

uri

OUT

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

xctx

IN

node

IN

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

xctx

IN

node

IN

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

xctx

IN

node

IN

buf

IN

buflen

IN

len

OUT

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

xctx

IN

node

IN

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

xctx

IN

node

IN

buf

IN

buflen

IN

len

OUT

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

xctx

IN

node

IN

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:

• ELEMENT_NODE=1

• ATTRIBUTE_NODE=2

• TEXT_NODE=3

• CDATA_SECTION_NODE=4

• ENTITY_REFERENCE_NODE=5

• ENTITY_NODE=6

• PROCESSING_INSTRUCTION_NODE=7

• COMMENT_NODE=8

• DOCUMENT_NODE=9

• DOCUMENT_TYPE_NODE=10

• DOCUMENT_FRAGMENT_NODE=11

• NOTATION_NODE=12

Additional Oracle extension node types are as follows:

• ELEMENT_DECL_NODE

• ATTR_DECL_NODE

• CP_ELEMENT_NODE

• CP_CHOICE_NODE

• CP_PCDATA_NODE

• CP_STAR_NODE

• CP_PLUS_NODE

• CP_OPT_NODE

Syntax

xmlnodetype XmlDomGetNodeType(
   xmlctx *xctx,
   xmlnode *node);

xctx

IN

node

IN

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

xctx

IN

node

IN

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

xctx

IN

node

IN

buf

IN

buflen

IN

len

OUT

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

xctx

IN

node

IN

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

xctx

IN

node

IN

buf

IN

buflen

IN

len

OUT

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

xctx

IN

node

IN

ostream

IN

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

xctx

IN

node

IN

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

xctx

IN

node

IN

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

xctx

IN

node

IN

Returns

(xmlnode *) node immediately preceding node at same level

XmlDomGetPullNodeAsBinaryStream()

Returns the address of a binary stream using the pull paradigm.

Syntax

orastream *XmlDomGetPullNodeAsBinaryStream(
   xmlctx *xctx,
   xmlnode *node);

xctx

IN

node

IN

Returns

(orastream *) the readable binary stream; use OraStreamRead() on the output, not OraStreamReadChar()

XmlDomGetPullNodeAsCharacterStream()

Returns the address of a character stream using the pull paradigm.

Syntax

orastream *XmlDomGetPullNodeAsCharacterStream(
   xmlctx *xctx,
   xmlnode *node);

xctx

IN

node

IN

Returns

(orastream *) the readable character stream; use OraStreamReadChar() on the output, not OraStreamRead().

XmlDomGetPushNodeAsBinaryStream()

Returns the address of a binary stream, as an OUT ostream parameter, using the push paradigm.

Syntax

xmlerr XmlDomGetPushNodeAsBinaryStream(
   xmlctx *xctx,
   xmlnode *node,
   orastream *ostream);

xctx

IN

node

IN

ostream

OUT

Returns

(xmlerr *) error code, XMLERR_OK [] on success

XmlDomGetPushNodeAsCharacterStream()

Returns the address of a character stream, as an OUT ostream parameter, using the push paradigm.

Syntax

xmlerr XmlDomGetPushNodeAsCharacterStream(
   xmlctx *xctx,
   xmlnode *node,
   orastream *ostream);

xctx

IN

node

IN

ostream

IN

Returns

(xmlerr *) error code, XMLERR_OK [] on success

XmlDomGetSourceEntity()

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

Syntax

xmlentnode* XmlDomGetSourceEntity(
   xmlctx *xctx,
   xmlnode *node);

xctx

IN

node

IN

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

xctx

IN

node

IN

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

xctx

IN

node

IN

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

xctx

IN

elem

IN

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

xctx

IN

node

IN

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

xctx

IN

parent

IN

newChild

IN

refChild

IN

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

xctx

IN

node

IN

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