Document Interface

Table 4-3 summarizes the methods of 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.

xmlattrnode* XmlDomCreateAttr(
   xmlctx *xctx,
   xmldocnode *doc, 
   oratext *name, 
   oratext *value)

xctx

IN

doc

IN

name

IN

value

IN

(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.

xmlattrnode* XmlDomCreateAttrNS(
   xmlctx *xctx, 
   xmldocnode *doc, 
   oratext *uri, 
   oratext *qname,
   oratext *value)

xctx

IN

doc

IN

uri

IN

qname

IN

value

IN

(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.

xmlcdatanode* XmlDomCreateCDATA(
   xmlctx *xctx, 
   xmldocnode *doc, 
   oratext *data)

xctx

IN

doc

IN

data

IN

(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.

xmlcommentnode* XmlDomCreateComment(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *data)

xctx

IN

doc

IN

data

IN

(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.

xmlelemnode* XmlDomCreateElem(
   xmlctx *xctx, 
   xmldocnode *doc,
   oratext *tagname)

xctx

IN

doc

IN

tagname

IN

(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.

xmlelemnode* XmlDomCreateElemNS(
   xmlctx *xctx,
   xmldocnode *doc, 
   oratext *uri,
   oratext *qname)

xctx

IN

doc

IN

uri

IN

qname

IN

(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.

xmlentrefnode* XmlDomCreateEntityRef(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *name)

xctx

IN

doc

IN

name

IN

(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".

xmlfragnode* XmlDomCreateFragment(
   xmlctx *xctx,
   xmldocnode *doc)

xctx

IN

doc

IN

(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.

xmlpinode* XmlDomCreatePI(
   xmlctx *xctx
   xmldocnode *doc, 
   oratext *target,
   oratext *data)

xctx

IN

doc

IN

target

IN

data

IN

(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.

xmltextnode* XmlDomCreateText(
   xmlctx *xctx, 
   xmldocnode *doc,
   oratext *data)

xctx

IN

doc

IN

data

IN

(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.

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.

oratext *XmlDomGetBaseURI(
   xmlctx *xctx,
   xmldocnode *doc)

xctx

IN

doc

IN

(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.

xmldtdnode* XmlDomGetDTD(
   xmlctx *xctx,
   xmldocnode *doc)

xctx

IN

doc

IN

(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.

xmlerr XmlDomGetDecl(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext **ver, 
   oratext **enc,
   sb4 *std)

xctx

IN

doc

IN

ver

OUT

enc

OUT

std

OUT

(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.

xmlelemnode* XmlDomGetDocElem(
   xmlctx *xctx,
   xmldocnode *doc)

xctx

IN

doc

IN

(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.

xmlelemnode* XmlDomGetDocElemByID(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *id)

xctx

IN

doc

IN

id

IN

(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.

xmlnodelist* XmlDomGetDocElemsByTag(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *name)

xctx

IN

doc

IN

name

IN

(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.

xmlnodelist* XmlDomGetDocElemsByTagNS(
   xmlctx *xctx,
   xmldocnode *doc, 
   oratext *uri,
   oratext *local)

xctx

IN

doc

IN

uri

IN

local

IN

(xmlnodelist *) new NodeList containing all matched Elements.

XmlDomGetLastError

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

xmlerr XmlDomGetLastError(
   xmlctx *xctx,
   xmldocnode *doc)

xctx

IN

doc

IN

(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.

oratext* XmlDomGetSchema(
   xmlctx *xctx,
   xmldocnode *doc)

xctx

IN

doc

IN

(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.

xmlnode* XmlDomImportNode(
   xmlctx *xctx,
   xmldocnode *doc, 
   xmlctx *nctx,
   xmlnode *node,
   boolean deep)

xctx

IN

doc

IN

nctx

IN

node

IN

deep

IN

(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.

boolean XmlDomIsSchemaBased(
   xmlctx *xctx,
   xmldocnode *doc)

xctx

IN

doc

IN

(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.

oratext* XmlDomSaveString(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *str)

xctx

IN

doc

IN

str

IN

(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.

ub2* XmlDomSaveString2(
   xmlctx *xctx,
   xmldocnode *doc,
   ub2 *ustr)

xctx

IN

doc

IN

ustr

IN

(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.

xmlerr XmlDomSetBaseURI(
   xmlctx *xctx, 
   xmldocnode *doc, 
   oratext *uri)

xctx

IN

doc

IN

uri

IN

(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.

xmlerr XmlDomSetDTD(
   xmlctx *xctx, 
   xmldocnode *doc, 
   xmldtdnode *dtdnode)

xctx

IN

doc

IN

dtdnode

IN

(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.

ub4 XmlDomSetDocOrder(
   xmlctx *xctx, 
   xmldocnode *doc,
   ub4 start_id)

xctx

IN

doc

IN

start_id

IN

(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.

xmlerr XmlDomSetLastError(
   xmlctx *xctx, 
   xmldocnode *doc,
   xmlerr errcode)

xctx

IN

doc

IN

errcode

IN

(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.

xmlerr XmlDomSync(
   xmlctx *xctx, 
   xmldocnode *doc)

xctx

IN

doc

IN

(xmlerr) numeric error code, 0 on success