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. |
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)
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 |
(xmlattrnode *)
new Attr
node.
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)
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 |
(xmlattrnode *)
new Attr
node.
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
data |
IN |
new node's CDATA ; data encoding; user control
|
(xmlcdatanode *)
new CDATA
node.
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
data |
IN |
new node's comment; data encoding; user control |
(xmlcommentnode *)
new Comment
node.
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
tagname |
IN |
new node's name; data encoding; user control |
(xmlelemnode *)
new Element
node.
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)
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 |
(xmlelemnode *)
new Element
node.
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
name |
IN |
name of referenced entity; data encoding; user control |
(xmlentrefnode *)
new EntityReference
node.
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
(xmlfragnode *)
new empty DocumentFragment
node
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)
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 |
(xmlpinode *)
new PI node.
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
data |
IN |
new node's text; data encoding; user control |
(xmltextnode *)
new Text
node.
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
document where the string belongs |
str |
IN |
string to free |
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
(oratext *)
document's base URI [or NULL
]
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
(xmldtdnode *)
DTD node for document [or NULL
]
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)
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 |
(xmlerr)
XML error code, perhaps version/encoding/standalone set
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
(xmlelemnode *)
root element [or NULL
]
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
id |
IN |
element's unique ID; data encoding |
(xmlelemnode *)
matching element.
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
name |
IN |
tagname to match; data encoding; * for all
|
(xmlnodelist *)
new NodeList
containing all matched Element
s.
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)
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
|
(xmlnodelist *)
new NodeList
containing all matched Element
s.
Returns the error code of the last error which occurred in the given document.
xmlerr XmlDomGetLastError( xmlctx *xctx, xmldocnode *doc)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
(xmlerr)
numeric error code, 0
if no error
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
(oratext *)
Schema URI or NULL
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)
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
|
(xmlnode *)
newly imported node (in this Document
).
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
(boolean)
TRUE
if there is a schema associated with the document
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)
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 |
(oratext *)
saved copy of string
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
ustr |
IN |
string to save; data encoding; Unicode only |
(ub2 *)
saved copy of string
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
uri |
IN |
base URI to set; data encoding |
(xmlerr)
XML error code
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
dtdnode |
IN |
DocumentType node to set
|
(xmlerr)
numeric error code, 0
on success
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
start_id |
IN |
string ID number |
(ub4)
highest ordinal assigned
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
errcode |
IN |
error code to set, 0 to clear error
|
(xmlerr)
original error code
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)
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
doc |
IN |
XML document node |
(xmlerr)
numeric error code, 0
on success