Document Interface

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

Table 4-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.

See Also:

XmlDomCleanNode, XmlDomFreeNode

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

See Also:

XmlDomSaveString, XmlDomSaveString2

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.

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