This implementation follows REC-DOM-Level-1-19981001. Because the DOM standard is object-oriented, some changes were made for C language adaptation.
Reused function names have to be expanded; getValue
in the Attr
interface has the unique name XmlDomGetAttrValue
that matches the pattern established by DOM 2's getNodeValue
.
Functions were added to extend the DOM beyond the standard; one example is XmlDomNumChildNodes
, which returns the number of children of a node.
This chapter contains the following sections:
Table 3-1 summarizes the methods of available through the Attr
interface.
Table 3-1 Summary of Attr Methods; DOM Package
Function | Summary |
---|---|
XmlDomGetAttrLocal() | Returns an attribute's namespace local name as NULL -terminated string. |
XmlDomGetAttrLocalLen() | Returns an attribute's namespace local name as length-encoded string. |
XmlDomGetAttrName() | Return attribute's name as NULL -terminated string. |
XmlDomGetAttrNameLen() | Return attribute's name as length-encoded string. |
XmlDomGetAttrPrefix() | Returns an attribute's namespace prefix. |
XmlDomGetAttrSpecified() | Return flag that indicates whether an attribute was explicitly created. |
XmlDomGetAttrURI() | Returns an attribute's namespace URI as NULL -terminated string. |
XmlDomGetAttrURILen() | Returns an attribute's namespace URI as length-encoded string. |
XmlDomGetAttrValue() | Return attribute's value as NULL -terminated string. |
XmlDomGetAttrValueLen() | Return attribute's value as length-encoded string. |
XmlDomGetAttrValueStream() | Get attribute value stream-style,i.e.chunked. |
XmlDomGetOwnerElem() | Return an attribute's "owning" element. |
XmlDomSetAttrValue() | Set an attribute's value. |
XmlDomSetAttrValueStream() | Sets an attribute value stream style (chunked). |
Returns an attribute's namespace local name (in the data encoding). If the attribute's name is not fully qualified (has no prefix), then the local name is the same as the name.
A length-encoded version is available as XmlDomGetAttrURILen
which returns the local name as a pointer and length, for use if the data is known to use XMLType
backing store.
Syntax
oratext* XmlDomGetAttrLocal( xmlctx *xctx, xmlattrnode *attr);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
attr |
IN |
attribute node |
Returns
(oratext *)
attribute's local name [data encoding]
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 Get
XXX
functions will avoid having to copy and NULL
-terminate the data.
If both the input buffer is non-NULL
and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.
If the actual length is greater than buflen
, then a truncated value will be copied into the buffer and len will return the actual length.
Syntax
oratext* XmlDomGetAttrLocalLen( xmlctx *xctx, xmlattrnode *attr, oratext *buf, ub4 buflen, ub4 *len);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
attr |
IN |
attribute node |
buf |
IN |
input buffer; optional |
buflen |
IN |
input buffer length; optional |
len |
OUT |
length of local name, in characters |
Returns
(oratext *)
Attr
's local name [data encoding]
Returns the fully-qualified name of an attribute (in the data encoding) as a NULL
-terminated string, for example bar\0
or foo:bar\0
.
A length-encoded version is available as XmlDomGetAttrNameLen
which returns the attribute name as a pointer and length, for use if the data is known to use XMLType
backing store.
Syntax
oratext* XmlDomGetAttrName( xmlctx *xctx, xmlattrnode *attr);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
attr |
IN |
attribute node |
Returns
(oratext *)
name of attribute [data encoding]
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 Get
XXX()
functions will avoid having to copy and NULL
-terminate the data.
If both the input buffer is non-NULL
and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.
If the actual length is greater than buflen
, then a truncated value will be copied into the buffer and len
will return the actual length.
Syntax
oratext* XmlDomGetAttrNameLen( xmlctx *xctx, xmlattrnode *attr, oratext *buf, ub4 buflen, ub4 *len);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
attr |
IN |
attribute node |
buf |
IN |
input buffer; optional |
buflen |
IN |
input buffer length; optional |
len |
OUT |
length of local name, in characters |
Returns
(oratext *)
name of attribute [data encoding]
Returns an attribute's namespace prefix (in the data encoding). If the attribute's name is not fully qualified (has no prefix), NULL
is returned.
Syntax
oratext* XmlDomGetAttrPrefix( xmlctx *xctx, xmlattrnode *attr);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
attr |
IN |
attribute node |
Returns
(oratext *)
attribute's namespace prefix [data encoding] or NULL
Return the 'specified' flag for an attribute. If the attribute was explicitly given a value in the original document, this is TRUE
; otherwise, it is FALSE
. If the node is not an attribute, returns FALSE
. If the user sets an attribute's value through DOM, its specified flag will be TRUE
. To return an attribute to its default value (if it has one), the attribute should be deleted; it will then be re-created automatically with the default value (and specified will be FALSE
).
Syntax
boolean XmlDomGetAttrSpecified( xmlctx *xctx, xmlattrnode *attr);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
attr |
IN |
attribute node |
Returns
(boolean)
attribute's "specified" flag
Returns an attribute's namespace URI (in the data encoding). If the attribute's name is not qualified (does not contain a namespace prefix), it will have the default namespace in effect when the node was created (which may be NULL
).
A length-encoded version is available as XmlDomGetAttrURILen
which returns the URI as a pointer and length, for use if the data is known to use XMLType
backing store.
Syntax
oratext* XmlDomGetAttrURI( xmlctx *xctx, xmlattrnode *attr);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
attr |
IN |
attribute node |
Returns
(oratext *)
attribute's namespace URI [data encoding] or NULL
Returns an attribute's namespace URI (in the data encoding) as length-encoded string. If the attribute's name is not qualified (does not contain a namespace prefix), it will have the default namespace in effect when the node was created (which may be NULL
).
A NULL
-terminated version is available as XmlDomGetAttrURI
which returns the URI as NULL
-terminated string. If the backing store is known to be XMLType
, then the attribute's data will be stored internally as length-encoded. Using the length-based Get functions will avoid having to copy and NULL
-terminate the data.
If both the input buffer is non-NULL
and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.
If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.
Syntax
oratext* XmlDomGetAttrURILen( xmlctx *xctx, xmlattrnode *attr, oratext *buf, ub4 buflen, ub4 *len);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
attr |
IN |
attribute node |
buf |
IN |
input buffer; optional |
buflen |
IN |
input buffer length; optional |
len |
OUT |
length of URI, in characters |
Returns
(oratext *)
attribute's namespace URI [data encoding] or NULL
Returns the "value" (character data) of an attribute (in the data encoding) as NULL
-terminated string. Character and general entities will have been replaced.
A length-encoded version is available as XmlDomGetAttrValueLen
which returns the attribute value as a pointer and length, for use if the data is known to use XMLType
backing store.
Syntax
oratext* XmlDomGetAttrValue( xmlctx *xctx, xmlattrnode *attr);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
attr |
IN |
attribute node |
Returns
(oratext *)
attribute's value
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 Get
XXX
() functions will avoid having to copy and NULL
-terminate the data.
If both the input buffer is non-NULL
and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.
If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.
Syntax
oratext* XmlDomGetAttrValueLen( xmlctx *xctx, xmlattrnode *attr, oratext *buf, ub4 buflen, ub4 *len);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
attr |
IN |
attribute node |
buf |
IN |
input buffer; optional |
buflen |
IN |
input buffer length; optional |
len |
OUT |
length of attribute's value, in characters |
Returns
(oratext *)
attribute's value
Returns the large "value" (associated character data) for an attribute and sends it in pieces to the user's output stream. For very large values, it is not always possible to store them [efficiently] as a single contiguous chunk. This function is used to access chunked data of that type.
Syntax
xmlerr XmlDomGetAttrValueStream( xmlctx *xctx, xmlnode *attr, xmlostream *ostream);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
attr |
IN |
attribute node |
ostream |
IN |
output stream object |
Returns
(xmlerr)
numeric error code, 0
on success
Returns the Element
node associated with an attribute. Each attr either belongs to an element (one and only one), or is detached and not yet part of the DOM tree. In the former case, the element node is returned; if the attr is unassigned, NULL
is returned.
Syntax
xmlelemnode* XmlDomGetOwnerElem( xmlctx *xctx, xmlattrnode *attr);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
attr |
IN |
attribute node |
Returns
(xmlelemnode *)
attribute's element node [or NULL
]
Sets the given attribute's value to data. If the node is not an attribute, does nothing. Note that the new value must be in the data encoding! It is not verified, converted, or checked. The attribute's specified flag will be TRUE
after setting a new value.
Syntax
void XmlDomSetAttrValue( xmlctx *xctx, xmlattrnode *attr, oratext *value);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
attr |
IN |
attribute node |
value |
IN |
new value of attribute; data encoding |
Sets the large "value" (associated character data) for an attribute piecemeal from an input stream. For very large values, it is not always possible to store them efficiently as a single contiguous chunk. This function is used to access chunked data of that type.
Syntax
xmlerr XmlDomSetAttrValueStream( xmlctx *xctx, xmlnode *attr, xmlistream *istream);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
attr |
IN |
attribute node |
isream |
IN |
input stream |
Returns
(xmlerr)
numeric error code, 0
on success
Table 3-2 summarizes the methods of available through the CharacterData
interface.
Table 3-2 Summary of CharacterData Method; DOM Package
Function | Summary |
---|---|
XmlDomAppendData() | Append data to end of node's current data. |
XmlDomDeleteData() | Remove part of node's data. |
XmlDomGetCharData() | Return data for node. |
XmlDomGetCharDataLength() | Return length of data for node. |
XmlDomInsertData() | Insert string into node's current data. |
XmlDomReplaceData() | Replace part of node's data. |
XmlDomSetCharData() | Set data for node. |
XmlDomSubstringData() | Return substring of node's data. |
Append a string to the end of a CharacterData
node's data. If the node is not Text
, Comment
or CDATA
, or if the string to append is NULL
, does nothing. The appended data should be in the data encoding. It will not be verified, converted, or checked.
The new node data will be allocated and managed by DOM, but if the previous node value was allocated and manager by the user, they are responsible for freeing it, which is why it is returned.
Syntax
void XmlDomAppendData( xmlctx *xctx, xmlnode *node, oratext *data, oratext **old);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
CharacterData node |
data |
IN |
data to append; data encoding |
old |
OUT |
previous data for node; data encoding |
Remove a range of characters from a CharacterData
node's data. If the node is not text, comment or CDATA
, or if the offset is outside of the original data, does nothing. The offset
is zero-based, so offset zero refers to the start of the data. Both offset
and count
are in characters, not bytes. If the sum of offset and count exceeds the data length then all characters from offset
to the end of the data are deleted.
The new node data will be allocated and managed by DOM, but if the previous node value was allocated and managed by the user, they are responsible for freeing it, which is why it is returned.
Syntax
void XmlDomDeleteData( xmlctx *xctx, xmlnode *node, ub4 offset, ub4 count, oratext **old);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
CharacterData node |
offset |
IN |
character offset where to start removing |
count |
IN |
number of characters to delete |
old |
OUT |
previous data for node; data encoding |
Returns the data for a CharacterData
node (type text, comment or CDATA
) in the data encoding. For other node types, or if there is no data, returns NULL
.
Syntax
oratext* XmlDomGetCharData( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
CharacterData node; Text , Comment or CDATA |
Returns
(oratext *)
character data of node [data encoding]
Returns the length of the data for a CharacterData
node, type Text
, Comment
or CDATA
) in characters, not bytes. For other node types, returns 0.
Syntax
ub4 XmlDomGetCharDataLength( xmlctx *xctx, xmlnode *cdata);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
CharacterData node; Text , Comment or CDATA |
Returns
(ub4)
length in characters, not bytes, of node's data
Insert a string into a CharacterData
node's data at the specified position. If the node is not Text
, Comment
or CDATA
, or if the data to be inserted is NULL
, or the offset is outside the original data, does nothing. The inserted data must be in the data encoding. It will not be verified, converted, or checked. The offset is specified as characters, not bytes. The offset is zero-based, so inserting at offset zero prepends the data.
The new node data will be allocated and managed by DOM, but if the previous node value was allocated and managed by the user, they are responsible for freeing it (which is why it's returned).
Syntax
void XmlDomInsertData( xmlctx *xctx, xmlnode *node, ub4 offset, oratext *arg, oratext **old);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
CharacterData node; Text , Comment , or CDATA |
offset |
IN |
character offset where to start inserting |
arg |
IN |
data to insert |
old |
OUT |
previous data for node; data encoding |
Replaces a range of characters in a CharacterData
node's data with a new string. If the node is not text, comment or CDATA
, or if the offset is outside of the original data, or if the replacement string is NULL
, does nothing. If the count is zero, acts just as XmlDomInsertData
. The offset is zero-based, so offset zero refers to the start of the data. The replacement data must be in the data encoding. It will not be verified, converted, or checked. The offset and count are both in characters, not bytes. If the sum of offset and count exceeds length, then all characters to the end of the data are replaced.
The new node data will be allocated and managed by DOM, but if the previous node value was allocated and managed by the user, they are responsible for freeing it, which is why it is returned.
Syntax
void XmlDomReplaceData( xmlctx *xctx, xmlnode *node, ub4 offset, ub4 count, oratext *arg, oratext **old);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
CharacterData node; Text , Comment , or CDATA |
offset |
IN |
character offset where to start replacing |
count |
IN |
number of characters to replace |
arg |
IN |
replacement substring; data encoding |
old |
OUT |
previous data for node; data encoding |
Sets data for a CharacterData
node (type text, comment or CDATA
), replacing the old data. For other node types, does nothing. The new data is not verified, converted, or checked; it should be in the data encoding.
Syntax
void XmlDomSetCharData( xmlctx *xctx, xmlnode *node, oratext *data);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
CharacterData node; Text , Comment , or CDATA |
data |
IN |
new data for node |
Returns a range of character data from a CharacterData
node, type Text
, Comment
or CDATA
. For other node types, or if count is zero, returns NULL
. Since the data is in the data encoding, offset and count are in characters, not bytes. The beginning of the string is offset 0
. If the sum of offset and count exceeds the length, then all characters to the end of the data are returned.
The substring is permanently allocated in the node's document's memory pool. To free the substring, use XmlDomFreeString
.
Syntax
oratext* XmlDomSubstringData( xmlctx *xctx, xmlnode *node, ub4 offset, ub4 count);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
CharacterData node; Text , Comment , or CDATA |
offset |
IN |
character offset where to start extraction of substring |
count |
IN |
number of characters to extract |
Returns
(oratext *)
specified substring.
Table 3-3 summarizes the methods of available through the Document
interface.
Table 3-3 Summary of Document Methods; DOM Package
Function | Summary |
---|---|
XmlDomCreateAttr() | Create attribute node. |
XmlDomCreateAttrNS() | Create attribute node with namespace information. |
XmlDomCreateCDATA() | Create CDATA node. |
XmlDomCreateComment() | Create comment node. |
XmlDomCreateElem() | Create an element node. |
XmlDomCreateElemNS() | Create an element node with namespace information. |
XmlDomCreateEntityRef() | Create entity reference node. |
XmlDomCreateFragment() | Create a document fragment. |
XmlDomCreatePI() | Create PI node. |
XmlDomCreateText() | Create text node. |
XmlDomFreeString() | Frees a string allocate by XmlDomSubstringData , and others. |
XmlDomGetBaseURI() | Returns the base URI for a document. |
XmlDomGetDTD() | Get DTD for document. |
XmlDomGetDecl() | Returns a document's XMLDecl information. |
XmlDomGetDocElem() | Get top-level element for document. |
XmlDomGetDocElemByID() | Get document element given ID. |
XmlDomGetDocElemsByTag() | Obtain document elements. |
XmlDomGetDocElemsByTagNS() | Obtain document elements (namespace aware version). |
XmlDomGetLastError() | Return last error code for document. |
XmlDomGetSchema() | Returns URI of schema associated with document. |
XmlDomImportNode() | Import a node from another DOM. |
XmlDomIsSchemaBased() | Indicate whether a schema is associated with a document. |
XmlDomSaveString() | Saves a string permanently in a document's memory pool. |
XmlDomSaveString2() | Saves a Unicode string permanently in a document's memory pool. |
XmlDomSetDTD() | Sets DTD for document. |
XmlDomSetDocOrder() | Set document order for all nodes. |
XmlDomSetLastError() | Sets last error code for document. |
XmlDomSync() | Synchronizes the persistent version of a document with its DOM. |
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
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 |
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
]
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
]
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
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
]
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.
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 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.
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 Element
s.
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
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
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
).
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
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
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
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
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
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
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
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
Table 3-4 summarizes the methods of available through the DocumentType
interface.
Table 3-4 Summary of DocumentType Methods; DOM Package
Function | Summary |
---|---|
XmlDomGetDTDEntities() | Get entities of DTD. |
XmlDomGetDTDInternalSubset() | Get DTD's internal subset. |
XmlDomGetDTDName() | Get name of DTD. |
XmlDomGetDTDNotations() | Get notations of DTD. |
XmlDomGetDTDPubID() | Get DTD's public ID. |
XmlDomGetDTDSysID() | Get DTD's system ID. |
Returns a named node map of general entities defined by the DTD. If the node is not a DTD, or has no general entities, returns NULL
.
Syntax
xmlnamedmap* XmlDomGetDTDEntities( xmlctx *xctx, xmldtdnode *dtd);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
dtd |
IN |
DTD node |
Returns
(xmlnamedmap *)
named node map containing entities declared in DTD
Returns the content model for an element. If there is no DTD, returns NULL
.
Syntax
xmlnode* XmlDomGetDTDInternalSubset( xmlctx *xctx, xmldtdnode *dtd, oratext *name);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
dtd |
IN |
DTD node |
name |
IN |
name of Element ; data encoding |
Returns
(xmlnode *)
content model subtree
Returns a DTD's name (specified immediately after the DOCTYPE
keyword), or NULL
if the node is not type DTD.
Syntax
oratext* XmlDomGetDTDName( xmlctx *xctx, xmldtdnode *dtd);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
dtd |
IN |
DTD node |
Returns
(oratext *)
name of DTD
Returns named node map of notations declared by the DTD. If the node is not a DTD or has no Notation
s, returns NULL
.
Syntax
xmlnamedmap* XmlDomGetDTDNotations( xmlctx *xctx, xmldtdnode *dtd);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
dtd |
IN |
DTD node |
Returns
(xmlnamedmap *)
named node map containing notations declared in DTD
Returns a DTD's public identifier.
Syntax
oratext* XmlDomGetDTDPubID( xmlctx *xctx, xmldtdnode *dtd);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
dtd |
IN |
DTD node |
Returns
(oratext *)
DTD's public identifier [data encoding]
Returns a DTD's system identifier.
Syntax
oratext* XmlDomGetDTDSysID( xmlctx *xctx, xmldtdnode *dtd);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
dtd |
IN |
DTD node |
Returns
(oratext *)
DTD's system identifier [data encoding]
Table 3-5 summarizes the methods of available through the Element
Interface.
Table 3-5 Summary of Element Methods; DOM Package
Function | Summary |
---|---|
XmlDomGetAttr() | Return attribute's value given its name. |
XmlDomGetAttrNS() | Return attribute's value given its URI and local name. |
XmlDomGetAttrNode() | Get attribute by name. |
XmlDomGetAttrNodeNS() | Get attribute by name (namespace aware version). |
XmlDomGetChildrenByTag() | Get children of element with given tag name (non-namespace aware). |
XmlDomGetChildrenByTagNS() | Get children of element with tag name (namespace aware version). |
XmlDomGetDocElemsByTag() | Obtain doc elements. |
XmlDomGetDocElemsByTagNS() | Obtain doc elements (namespace aware version). |
XmlDomGetTag() | Return an element node's tag name. |
XmlDomHasAttr() | Does named attribute exist? |
XmlDomHasAttrNS() | Does named attribute exist (namespace aware version)? |
XmlDomRemoveAttr() | Remove attribute with specified name. |
XmlDomRemoveAttrNS() | Remove attribute with specified URI and local name. |
XmlDomRemoveAttrNode() | Remove attribute node. |
XmlDomSetAttr() | Set new attribute for element. |
XmlDomSetAttrNS() | Set new attribute for element (namespace aware version). |
XmlDomSetAttrNode() | Set attribute node. |
XmlDomSetAttrNodeNS() | Set attribute node (namespace aware version). |
Returns the value of an element's attribute (specified by name). Note that an attribute may have the empty string as its value, but cannot be NULL
. If the element does not have an attribute with the given name, NULL
is returned.
Syntax
oratext* XmlDomGetAttr( xmlctx *xctx, xmlelemnode *elem, oratext *name);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
element node |
name |
IN |
attribute's name |
Returns
(oratext *)
named attribute's value [data encoding; may be NULL
]
Returns the value of an element's attribute (specified by URI and local name). Note that an attribute may have the empty string as its value, but cannot be NULL
. If the element does not have an attribute with the given name, NULL
is returned.
Syntax
oratext* XmlDomGetAttrNS( xmlctx *xctx, xmlelemnode *elem, oratext *uri, oratext *local);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
element node |
uri |
IN |
attribute's namespace URI; data encoding |
local |
IN |
attribute's local name; data encoding |
Returns
(oratext *)
named attribute's value [data encoding; may be NULL
]
Returns an element's attribute specified by name. If the node is not an element or the named attribute does not exist, returns NULL
.
Syntax
xmlattrnode* XmlDomGetAttrNode( xmlctx *xctx, xmlelemnode *elem, oratext *name);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
element node |
name |
IN |
attribute's name; data encoding |
Returns
(xmlattrnode *)
attribute with the specified name [or NULL
]
Returns an element's attribute specified by URI and localname. If the node is not an element or the named attribute does not exist, returns NULL
.
Syntax
xmlattrnode* XmlDomGetAttrNodeNS( xmlctx *xctx, xmlelemnode *elem, oratext *uri, oratext *local);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
element node |
uri |
IN |
attribute's namespace URI; data encoding |
local |
IN |
attribute's local name; data encoding |
Returns
(xmlattrnode *)
attribute node with the given URI/local name [or NULL
]
Returns a list of children of an element with the given tag name, in the order in which they would be encountered in a preorder traversal of the tree. The tag name should be in the data encoding. The special name "*
" matches all tag names; a NULL
name matches nothing. Note that tag names are case sensitive. This function is not namespace aware; the full tag names are compared. If two prefixes which map to the same URI are compared, the comparison will fail. See XmlDomGetChildrenByTagNS
for the namespace-aware version. The returned list can be freed with XmlDomFreeNodeList
.
Syntax
xmlnodelist* XmlDomGetChildrenByTag( xmlctx *xctx, xmlelemnode *elem, oratext *name);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
element node |
name |
IN |
tag name to match; data encoding; * for all |
Returns
(xmlnodelist *)
node list of matching children
Returns a list of children of an element with the given URI and local name, in the order in which they would be encountered in a preorder traversal of the tree. The URI and local name should be in the data encoding. The special name "*
" matches all URIs or tag names; a NULL
name matches nothing. Note that names are case sensitive. See XmlDomGetChildrenByTag
for the non-namespace version. The returned list can be freed with XmlDomFreeNodeList
.
Syntax
xmlnodelist* XmlDomGetChildrenByTagNS( xmlctx *xctx, xmlelemnode *elem, oratext *uri, oratext *local);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
element node |
uri |
IN |
namespace URI to match; data encoding; * matches all |
local |
IN |
local name to match; data encoding; * matches all |
Returns
(xmlnodelist *)
node list of matching children
Returns a list of all elements (in the document tree rooted at the root node) with a given tag name, in the order in which they would be encountered in a preorder traversal of the tree. If root is NULL
, the entire document is searched. The tag name should be in the data encoding. The special name "*
" matches all tag names; a NULL
name matches nothing. Note that tag names are case sensitive. This function is not namespace aware; the full tag names are compared. If two prefixes which map to the same URI are compared, the comparison will fail. See XmlDomGetElemsByTagNS
for the namespace-aware version. The returned list can be freed with XmlDomFreeNodeList
.
Syntax
xmlnodelist* XmlDomGetElemsByTag( xmlctx *xctx, xmlelemnode *elem, oratext *name);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
element node |
name |
IN |
tag name to match; data encoding; * for all |
Returns
(xmlnodelist *)
node list of matching elements
Returns a list of all elements (in the document tree rooted at the root node) with a given URI and localname, in the order in which they would be encountered in a preorder traversal of the tree. If root is NULL
, the entire document is searched. The tag name should be in the data encoding. The special name "**
" matches all tag names; a NULL
name matches nothing. Note that tag names are case sensitive. This function is not namespace aware; the full tag names are compared. If two prefixes which map to the same URI are compared, the comparison will fail. The returned list can be freed with XmlDomFreeNodeList
.
Syntax
xmlnodelist* XmlDomGetElemsByTagNS( xmlctx *xctx, xmlelemnode *elem, oratext *uri, oratext *local);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
element node |
uri |
IN |
namespace URI to match; data encoding; * for all |
local |
IN |
local name to match; data encoding; * for all |
Returns
(xmlnodelist *)
node list of matching elements
Returns the tagName
} of a node, which is the same as its name. DOM 1.0 states "...even though there is a generic nodeName
attribute on the Node
interface, there is still a tagName
attribute on the Element
interface; these two attributes must contain the same value, but the Working Group considers it worthwhile to support both, given the different constituencies the DOM API must satisfy."
Syntax
oratext* XmlDomGetTag( xmlctx *xctx, xmlelemnode *elem);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
Element node |
Returns
(oratext *)
element's name [data encoding]
Determines if an element has an attribute with the given name. Returns TRUE
if so, FALSE
if not.
Syntax
boolean XmlDomHasAttr( xmlctx *xctx, xmlelemnode *elem, oratext *name);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
Element node |
name |
IN |
attribute's name; data encoding |
Returns
(boolean)
TRUE
if element has attribute with given name
Determines if an element has an attribute with the given URI and localname. Returns TRUE
if so, FALSE
if not.
Syntax
boolean XmlDomHasAttrNS( xmlctx *xctx, xmlelemnode *elem, oratext *uri, oratext *local);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
Element node |
uri |
IN |
attribute's namespace URI; data encoding |
local |
IN |
attribute's local name; data encoding |
Returns
(boolean)
TRUE
if element has attribute with given URI/localname
Removes an attribute (specified by name). If the removed attribute has a default value it is immediately re-created with that default. Note that the attribute is removed from the element's list of attributes, but the attribute node itself is not destroyed.
Syntax
void XmlDomRemoveAttr( xmlctx *xctx, xmlelemnode *elem, oratext *name);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
element node |
name |
IN |
attribute's name; data encoding |
Removes an attribute (specified by URI and local name). If the removed attribute has a default value it is immediately re-created with that default. Note that the attribute is removed from the element's list of attributes, but the attribute node itself is not destroyed.
Syntax
void XmlDomRemoveAttrNS( xmlctx *xctx, xmlelemnode *elem, oratext *uri, oratext *local);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
element node |
uri |
IN |
attribute's namespace URI |
local |
IN |
attribute's local name |
Removes an attribute from an element. If the attribute has a default value, it is immediately re-created with that value (Specified set to FALSE
). Returns the removed attribute on success, else NULL
.
Syntax
xmlattrnode* XmlDomRemoveAttrNode( xmlctx *xctx, xmlelemnode *elem, xmlattrnode *oldAttr);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
element node |
oldAtrr |
IN |
attribute node to remove |
Returns
(xmlattrnode *)
replaced attribute node [or NULL
]
Creates a new attribute for an element with the given name and value (which should be in the data encoding). If the named attribute already exists, its value is simply replaced. The name and value are not verified, converted, or checked. The value is not parsed, so entity references will not be expanded. The attribute's specified flag will be set.
Syntax
void XmlDomSetAttr( xmlctx *xctx, xmlelemnode *elem, oratext *name, oratext *value);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
element node |
name |
IN |
attribute's name; data encoding |
value |
IN |
attribute's value; data encoding |
Creates a new attribute for an element with the given URI, localname and value (which should be in the data encoding). If the named attribute already exists, its value is simply replaced. The name and value are not verified, converted, or checked.
The value is not parsed, so entity references will not be expanded.
The attribute's specified flag will be set.
Syntax
void XmlDomSetAttrNS( xmlctx *xctx, xmlelemnode *elem, oratext *uri, oratext *qname, oratext *value);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
element node |
uri |
IN |
attribute's namespace URI; data encoding |
qname |
IN |
attribute's qualified name; data encoding |
value |
IN |
attribute's value; data encoding |
Adds a new attribute to an element. If an attribute with the given name already exists, it is replaced and the old attribute returned through oldNode
. If the attribute is new, it is added to the element's list and oldNode
set to NULL
.
Syntax
xmlattrnode* XmlDomSetAttrNode( xmlctx *xctx, xmlelemnode *elem, xmlattrnode *newAttr);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
element node |
newAttr |
IN |
attribute node to add |
Returns
(xmlattrnode *)
replaced attribute node (or NULL
)
Adds a new attribute to an element. If an attribute with newNode
's URI and localname already exists, it is replaced and the old attribute returned through oldNode
. If the attribute is new, it is added to the element's list and oldNode
set to NULL
.
Syntax
xmlattrnode* XmlDomSetAttrNodeNS( xmlctx *xctx, xmlelemnode *elem, xmlattrnode *newAttr);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
element node |
newAttr |
IN |
attribute node to add |
Returns
(xmlattrnode *)
replaced attribute node [or NULL
]
Table 3-6 summarizes the methods of available through the Entity
interface.
Table 3-6 Summary of Entity Methods; DOM Package
Function | Summary |
---|---|
XmlDomGetEntityNotation() | Get entity's notation. |
XmlDomGetEntityPubID() | Get entity's public ID. |
XmlDomGetEntitySysID() | Get entity's system ID. |
XmlDomGetEntityType() | Get entity's type. |
For unparsed entities, returns the name of its notation (in the data encoding). For parsed entities and other node types, returns NULL
.
Syntax
oratext* XmlDomGetEntityNotation( xmlctx *xctx, xmlentnode *ent);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
ent |
IN |
entity node |
Returns
(oratext *)
entity's notation [data encoding; may be NULL
]
Returns an entity's public identifier (in the data encoding). If the node is not an entity, or has no defined public ID, returns NULL
.
Syntax
oratext* XmlDomGetEntityPubID( xmlctx *xctx, xmlentnode *ent);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
ent |
IN |
entity node |
Returns
(oratext *)
entity's public identifier [data encoding; may be NULL
]
Returns an entity's system identifier (in the data encoding). If the node is not an entity, or has no defined system ID, returns NULL
.
Syntax
oratext* XmlDomGetEntitySysID( xmlctx *xctx, xmlentnode *ent);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
ent |
IN |
entity node |
Returns
(oratext *)
entity's system identifier [data encoding; may be NULL
]
Returns a boolean for an entity describing whether it is general (TRUE
) or parameter (FALSE
).
Syntax
boolean XmlDomGetEntityType( xmlctx *xctx, xmlentnode *ent);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
ent |
IN |
entity node |
Returns
(boolean)
TRUE
for general entity, FALSE
for parameter entity
Table 3-7 summarizes the methods of available through the NamedNodeMap
interface.
Table 3-7 Summary of NamedNodeMap Methods; DOM Package
Function | Summary |
---|---|
XmlDomGetNamedItem() | Return named node from list. |
XmlDomGetNamedItemNS() | Return named node from list (namespace aware version). |
XmlDomGetNodeMapItem() | Return nth node in list. |
XmlDomGetNodeMapLength() | Return length of named node map. |
XmlDomRemoveNamedItem() | Remove node from named node map. |
XmlDomRemoveNamedItemNS() | Remove node from named node map (namespace aware version). |
XmlDomSetNamedItem() | Set node in named node list. |
XmlDomSetNamedItemNS() | Set node in named node list (namespace aware version). |
Retrieves an item from a NamedNodeMap
, specified by name (which should be in the data encoding). This is a non-namespace-aware function; it just matches (case sensitively) on the whole qualified name. Note this function differs from the DOM spec in that the index of the matching item is also returned.
Syntax
xmlnode* XmlDomGetNamedItem( xmlctx *xctx, xmlnamedmap *map, oratext *name);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
map |
IN |
NamedNodeMap |
name |
IN |
name of the node to retrieve |
Returns
(xmlnode *)
Node
with the specified name [or NULL
]
Retrieves an item from a NamedNodeMap
, specified by URI and localname (which should be in the data encoding). Note this function differs from the DOM spec in that the index of the matching item is also returned.
Syntax
xmlnode* XmlDomGetNamedItemNS( xmlctx *xctx, xmlnamedmap *map, oratext *uri, oratext *local);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
map |
IN |
NamedNodeMap |
uri |
IN |
namespace URI of the node to retrieve; data encoding |
local |
IN |
local name of the node to retrieve; data encoding |
Returns
(xmlnode *)
node with given local name and namespace URI [or NULL
]
Retrieves an item from a NamedNodeMap
, specified by name (which should be in the data encoding). This is a non-namespace-aware function; it just matches (case sensitively) on the whole qualified name. Note this function differs from the DOM specification in that the index of the matching item is also returned. Named "item" in W3C specification.
Syntax
xmlnode* XmlDomGetNodeMapItem( xmlctx *xctx, xmlnamedmap *map, ub4 index);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
map |
IN |
NamedNodeMap |
index |
IN |
0 -based index for the map |
Returns
(xmlnode *)
node at the nth position in the map (or NULL
)
Returns the number of nodes in a NamedNodeMap
(the length). Note that nodes are referred to by index, and the range of valid indexes is 0
through length-1.
Syntax
ub4 XmlDomGetNodeMapLength( xmlctx *xctx, xmlnamedmap *map);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
map |
IN |
NamedNodeMap |
Returns
(ub4)
number of nodes in NamedNodeMap
Removes a node from a NamedNodeMap
, specified by name. This is a non-namespace-aware function; it just matches (case sensitively) on the whole qualified name. If the removed node is an attribute with default value (not specified), it is immediately replaced. The removed node is returned; if no removal took place, NULL
is returned.
Syntax
xmlnode* XmlDomRemoveNamedItem( xmlctx *xctx, xmlnamedmap *map, oratext *name);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
map |
IN |
NamedNodeMap |
name |
IN |
name of node to remove |
Returns
(xmlnode *)
node removed from this map
Removes a node from a NamedNodeMap
, specified by URI and localname. If the removed node is an attribute with default value (not specified), it is immediately replaced. The removed node is returned; if no removal took place, NULL
is returned.
Syntax
xmlnode* XmlDomRemoveNamedItemNS( xmlctx *xctx, xmlnamedmap *map, oratext *uri, oratext *local);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
map |
IN |
NamedNodeMap |
uri |
IN |
namespace URI of the node to remove; data encoding |
local |
IN |
local name of the node to remove; data encoding |
Returns
(xmlnode *)
node removed from this map
Adds a new node to a NamedNodeMap
. If a node already exists with the given name, replaces the old node and returns it. If no such named node exists, adds the new node to the map and sets old to NULL
. This is a non-namespace-aware function; it just matches (case sensitively) on the whole qualified name. Since some node types have fixed names (Text
, Comment
, and so on), trying to set another of the same type will always cause replacement.
Syntax
xmlnode* XmlDomSetNamedItem( xmlctx *xctx, xmlnamedmap *map, xmlnode *newNode);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
map |
IN |
NamedNodeMap |
newNode |
IN |
new node to store in map |
Returns
(xmlnode *)
the replaced node (or NULL
)
Adds a new node to a NamedNodeMap
. If a node already exists with the given URI and localname, replaces the old node and returns it. If no such named node exists, adds the new node to the map and sets old to NULL
. Since some node types have fixed names (Text
, Comment
, and so on), trying to set another of the same type will always cause replacement.
Syntax
xmlnode* XmlDomSetNamedItemNS( xmlctx *xctx, xmlnamedmap *map, xmlnode *newNode);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
map |
IN |
NamedNodeMap |
newNode |
IN |
new node to store in map |
Returns
(xmlnode *)
replaced Node
[or NULL
]
Table 3-8 summarizes the methods of available through the Node
interface.
Table 3-8 Summary of Text Methods; DOM Package
Function | Summary |
---|---|
XmlDomAppendChild() | Append new child to node's list of children. |
XmlDomCleanNode() | Clean a node (free DOM allocations). |
XmlDomCloneNode() | Clone a node. |
XmlDomFreeNode() | Free a node allocated with XmlDomCreateXXX . |
XmlDomGetAttrs() | Return attributes of node. |
XmlDomGetChildNodes() | Return children of node. |
XmlDomGetDefaultNS() | Get default namespace for node. |
XmlDomGetFirstChild() | Returns first child of node. |
XmlDomGetFirstPfnsPair() | Get first prefix namespace pair. |
XmlDomGetLastChild() | Returns last child of node. |
XmlDomGetNextPfnsPair() | Get subsequent prefix namespace pair. |
XmlDomGetNextSibling() | Return next sibling of node. |
XmlDomGetNodeLocal() | Get local part of node's qualified name as NULL -terminated string. |
XmlDomGetNodeLocalLen() | Get local part of node's qualified name as length-encoded string. |
XmlDomGetNodeName() | Get node's name as NULL -terminated string. |
XmlDomGetNodeNameLen() | Get node's name as length-encoded string. |
XmlDomGetNodePrefix() | Return namespace prefix of node. |
XmlDomGetNodeType() | Get node's numeric type code. |
XmlDomGetNodeURI() | Return namespace URI of node as a NULL -terminated string. |
XmlDomGetNodeURILen() | Return namespace URI of node as length-encoded string. |
XmlDomGetNodeValue() | Get node's value as NULL -terminated string. |
XmlDomGetNodeValueLen() | Get node value as length-encoded string. |
XmlDomGetNodeValueStream() | Get node value stream-style (chunked). |
XmlDomGetOwnerDocument() | Get the owner document of node. |
XmlDomGetParentNode() | Get parent node. |
XmlDomGetPrevSibling() | Return previous sibling of node. |
XmlDomGetSourceEntity() | Return the entity node if the input file is an external entity. |
XmlDomGetSourceLine() | Return source line number of node. |
XmlDomGetSourceLocation() | Return source location (path, URI, and so on) of node. |
XmlDomHasAttr() | Does named attribute exist? |
XmlDomHasChildNodes() | Test if node has children. |
XmlDomInsertBefore() | Insert new child in to node's list of children. |
XmlDomNormalize() | Normalize a node by merging adjacent text nodes. |
XmlDomNumAttrs() | Return number of attributes of element. |
XmlDomNumChildNodes() | Return number of children of node. |
XmlDomPrefixToURI() | Get namespace URI for prefix. |
XmlDomRemoveChild() | Remove an existing child node. |
XmlDomReplaceChild() | Replace an existing child of a node. |
XmlDomSetDefaultNS() | Set default namespace for node. |
XmlDomSetNodePrefix() | Set namespace prefix of node. |
XmlDomSetNodeValue() | Set node value. |
XmlDomSetNodeValueLen() | Set node value as length-encoded string. |
XmlDomSetNodeValueStream() | Set node value stream-style (chunked). |
XmlDomValidate() | Validate a node against current DTD. |
Appends the node to the end of the parent's list of children and returns the new node. If newChild
is a DocumentFragment
, all of its children are appended in original order; the DocumentFragment
node itself is not.
Syntax
xmlnode* XmlDomAppendChild( xmlctx *xctx, xmlnode *parent, xmlnode *newChild);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
parent |
IN |
parent to receive a new node |
newChild |
IN |
node to add |
Returns
(xmlnode *)
node added
Frees parts of the node which were allocated by DOM itself, but does not recurse to children or touch the node's attributes. After freeing part of the node (such as name), a DOM call to get that part (such as XmlDomGetNodeName
) should return a NULL
pointer. Used to manage the allocations of a node parts of which are controlled by DOM, and part by the user. Calling clean frees all allocations may by DOM and leaves the user's allocations alone. The user is responsible for freeing their own allocations.
Syntax
void XmlDomCleanNode( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
node to clean |
Creates and returns a duplicate of a node. The duplicate node has no parent. Cloning an element copies all attributes and their values, including those generated by the XML processor to represent defaulted attributes, but it does not copy any text it contains unless it is a deep clone, since the text is contained in a child text node. Cloning any other type of node simply returns a copy of the node. Note that a clone of an unspecified attribute node is specified. If deep is TRUE
, all children of the node are recursively cloned, and the cloned node will have cloned children; a non-deep clone will have no children.
Syntax
xmlnode* XmlDomCloneNode( xmlctx *xctx, xmlnode *node, boolean deep);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
deep |
IN |
TRUE to recursively clone children |
Returns
(xmlnode *)
duplicate (cloned) node
Free a node allocated with XmlDomCreate
XXX
. Frees all resources associated with a node, then frees the node itself. Certain parts of the node are under DOM control, and some parts may be under user control. DOM keeps flags tracking who owns what, and only frees its own allocations. The user is responsible for freeing their own parts of the node before calling XmlDomFreeNode.
Syntax
void XmlDomFreeNode( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node to free |
Returns a NamedNodeMap
of attributes of an element node, or NULL
if it has no attributes. For other node types, NULL
is returned. Note that if an element once had attributes, but they have all been removed, an empty list will be returned. So, presence of the list does not mean the element has attributes. You must check the size of the list with XmlDomNumAttrs
or use XmlDomHasChildNodes
first.
Syntax
xmlnamedmap* XmlDomGetAttrs( xmlctx *xctx, xmlelemnode *elem);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
XML element node |
Returns
(xmlnamedmap *)
NamedNodeMap
of node's attributes
Returns a list of the node's children, or NULL
if it has no children. Only Element
, Document
, DTD, and DocumentFragment
nodes may have children; all other types will return NULL
.
Note that an empty list may be returned if the node once had children, but all have been removed! That is, the list may exist but have no members. So, presence of the list alone does not mean the node has children. You must check the size of the list with XmlDomNumChildNodes
or use XmlDomHasChildNodes
first.
The xmlnodelist structure is opaque and can only be manipulated with functions in the NodeList
interface.
The returned list is live; all changes in the original node are reflected immediately.
Syntax
xmlnodelist* XmlDomGetChildNodes( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(xmlnodelist *)
live NodeList
containing all children of node
Gets the default namespace for a node.
Syntax
oratext* XmlDomGetDefaultNS( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
element or attribute DOM node |
Returns
(oratext *)
default namespace for node [data encoding; may be NULL
]
Returns the first child of a node, or NULL
if the node has no children. Only Element
, Document
, DTD, and DocumentFragment
nodes may have children; all other types will return NULL
.
Syntax
xmlnode* XmlDomGetFirstChild( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(xmlnode *)
first child of node
This function is to allow implementations an opportunity to speedup the iteration of all available prefix-URI bindings available on a given node. It returns a state structure and the prefix and URI of the first prefix-URI mapping. The state structure should be passed to XmlDomGetNextPfnsPair
on the remaining pairs.
Syntax
xmlpfnspair* XmlDomGetFirstPfnsPair( xmlctx *xctx, xmlnode *node, oratext **prefix, oratext **uri);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
prefix |
OUT |
prefix of first mapping; data encoding |
uri |
OUT |
URI of first mapping; data encoding |
Returns
(xmlpfnspair *)
iterating object or NULL
of no prefixes
Returns the last child of a node, or NULL
if the node has no children. Only Element
, Document
, DTD, and DocumentFragment
nodes may have children; all other types will return NULL
.
Syntax
xmlnode* XmlDomGetLastChild( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(xmlnode *)
last child of node
This function is to allow implementations an opportunity to speedup the iteration of all available prefix-URI bindings available on a given node. Given an iterator structure from XmlDomGetFirstPfnsPair
, returns the next prefix-URI mapping; repeat calls to XmlDomGetNextPfnsPair
until NULL
is returned.
Syntax
xmlpfnspair* XmlDomGetNextPfnsPair( xmlctx *xctx xmlpfnspair *pfns, oratext **prefix, oratext **uri);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
prefix |
OUT |
prefix of next mapping; data encoding |
uri |
OUT |
URI of next mapping; data encoding |
Returns
(xmlpfnspair *)
iterating object, NULL
when no more pairs
Returns the node following a node at the same level in the DOM tree. That is, for each child of a parent node, the next sibling of that child is the child which comes after it. If a node is the last child of its parent, or has no parent, NULL
is returned.
Syntax
xmlnode* XmlDomGetNextSibling( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(xmlnode *)
node immediately following node at same level
Returns the namespace local name for a node as a NULL
-terminated string. If the node's name is not fully qualified (has no prefix), then the local name is the same as the name.
A length-encoded version is available as XmlDomGetNodeLocalLen
which returns the local name as a pointer and length, for use if the data is known to use XMLType
backing store.
Syntax
oratext* XmlDomGetNodeLocal( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(oratext *)
local name of node [data encoding]
Returns the namespace local name for a node as a length-encoded string. If the node's name is not fully qualified (has no prefix), then the local name is the same as the name.
A NULL
-terminated version is available as XmlDomGetNodeLocal
which returns the local name as NULL
-terminated string. If the backing store is known to be XMLType
, then the node's data will be stored internally as length-encoded. Using the length-based Get functions will avoid having to copy and NULL
-terminate the data.
If both the input buffer is non-NULL
and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.
If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.
Syntax
oratext* XmlDomGetNodeLocalLen( xmlctx *xctx, xmlnode *node, oratext *buf, ub4 buflen, ub4 *len);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
buf |
IN |
input buffer; optional |
buflen |
IN |
input buffer length; optional |
len |
OUT |
length of local name, in characters |
Returns
(oratext *)
local name of node [data encoding]
Returns the (fully-qualified) name of a node (in the data encoding) as a NULL
-terminated string, for example bar\0
or foo:bar\0
.
Note that some node types have fixed names: "#text
", "#cdata-section
", "#comment
", "#document
", "#document-fragment
".
A node's name cannot be changed once it is created, so there is no matching SetNodeName
function.
A length-based version is available as XmlDomGetNodeNameLen
which returns the node name as a pointer and length, for use if the data is known to use XMLType
backing store.
Syntax
oratext* XmlDomGetNodeName( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(oratext *)
name of node [data encoding]
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 Get
XXX
functions will avoid having to copy and NULL
-terminate the name.
If both the input buffer is non-NULL
and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.
If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len
will return the actual length.
Syntax
oratext* XmlDomGetNodeNameLen( xmlctx *xctx, xmlnode *node, oratext *buf, ub4 buflen, ub4 *len);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
buf |
IN |
input buffer; optional |
buflen |
IN |
input buffer length; optional |
len |
OUT |
length of name, in characters |
Returns
(oratext *)
name of node, with length of name set in 'len'
Returns the namespace prefix for a node (as a NULL
-terminated string). If the node's name is not fully qualified (has no prefix), NULL
is returned.
Syntax
oratext* XmlDomGetNodePrefix( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(oratext *)
namespace prefix of node [data encoding; may be NULL
]
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);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(xmlnodetype)
numeric type-code of the node
Returns the namespace URI for a node (in the data encoding) as a NULL
-terminated string. If the node's name is not qualified (does not contain a namespace prefix), it will have the default namespace in effect when the node was created (which may be NULL
).
A length-encoded version is available as XmlDomGetNodeURILen
which returns the URI as a pointer and length, for use if the data is known to use XMLType
backing store.
Syntax
oratext* XmlDomGetNodeURI( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(oratext *)
namespace URI of node [data encoding; may be NULL
]
Returns the namespace URI for a node (in the data encoding) as length-encoded string. If the node's name is not qualified (does not contain a namespace prefix), it will have the default namespace in effect when the node was created (which may be NULL
).
A NULL
-terminated version is available as XmlDomGetNodeURI
which returns the URI value as NULL
-terminated string. If the backing store is known to be XMLType
, then the node's data will be stored internally as length-encoded. Using the length-based Get functions will avoid having to copy and NULL
-terminate the data.
If both the input buffer is non-NULL
and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.
If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len
will return the actual length.
Syntax
oratext* XmlDomGetNodeURILen( xmlctx *xctx, xmlnode *node, oratext *buf, ub4 buflen, ub4 *len);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
buf |
IN |
input buffer; optional |
buflen |
IN |
input buffer length; optional |
len |
OUT |
length of URI, in characters |
Returns
(oratext *)
namespace URI of node [data encoding; may be NULL
]
Returns the "value" (associated character data) for a node as a NULL
-terminated string. Character and general entities will have been replaced. Only Attr
, CDATA
, Comment
, ProcessingInstruction
and Text
nodes have values, all other node types have NULL
value.
A length-encoded version is available as XmlDomGetNodeValueLen
which returns the node value as a pointer and length, for use if the data is known to use XMLType
backing store.
Syntax
oratext* XmlDomGetNodeValue( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(oratext *)
value of node
Returns the "value" (associated character data) for a node as a length-encoded string. Character and general entities will have been replaced. Only Attr
, CDATA
, Comment
, PI and Text
nodes have values, all other node types have NULL
value.
A NULL
-terminated version is available as XmlDomGetNodeValue
which returns the node value as NULL
-terminated string. If the backing store is known to be XMLType
, then the node's data will be stored internally as length-encoded. Using the length-based Get functions will avoid having to copy and NULL
-terminate the data.
If both the input buffer is non-NULL
and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.
If the actual length is greater than buflen
, then a truncated value will be copied into the buffer and len will return the actual length.
Syntax
oratext* XmlDomGetNodeValueLen( xmlctx *xctx, xmlnode *node, oratext *buf, ub4 buflen, ub4 *len);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
buf |
IN |
input buffer; optional |
buflen |
IN |
input buffer length; optional |
len |
OUT |
length of value, in bytes |
Returns
(oratext *)
value of node
Returns the large data for a node and sends it in pieces to the user's output stream. For very large values, it is not always possible to store them [efficiently] as a single contiguous chunk. This function is used to access chunked data of that type. Only XMLType
chunks its data (sometimes); XDK's data is always contiguous.
Syntax
xmlerr XmlDomGetNodeValueStream( xmlctx *xctx, xmlnode *node, xmlostream *ostream);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
ostream |
IN |
output stream object |
Returns
(xmlerr)
numeric error code, 0
on success
Returns the Document
node associated with a node. Each node may belong to only one document, or may not be associated with any document at all (such as immediately after XmlDomCreateElem
, and so on). The "owning" document [node] is returned, or NULL
for an orphan node.
Syntax
xmldocnode* XmlDomGetOwnerDocument( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(xmldocnode *)
document node is in
Returns a node's parent node. All nodes types except Attr
, Document
, DocumentFragment
, Entity
, and Notation
may have a parent (these five exceptions always have a NULL
parent). If a node has just been created but not yet added to the DOM tree, or if it has been removed from the DOM tree, its parent is also NULL
.
Syntax
xmlnode* XmlDomGetParentNode( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(xmlnode *)
parent of node
Returns the node preceding a node at the same level in the DOM tree. That is, for each child of a parent node, the previous sibling of that child is the child which came before it. If a node is the first child of its parent, or has no parent, NULL
is returned.
Syntax
xmlnode* XmlDomGetPrevSibling( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(xmlnode *)
node immediately preceding node at same level
Returns the external entity node whose inclusion caused the creation of the given node.
Syntax
xmlentnode* XmlDomGetSourceEntity( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(xmlentnode *)
entity node if the input is from an external entity
Returns the line# in the original source where the node started. The first line in every input is line #1.
Syntax
ub4 XmlDomGetSourceLine( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(ub4)
line number of node in original input source
Return source location (path, URI, and so on) of node. Note this will be in the compiler encoding, not the data encoding!
Syntax
oratext* XmlDomGetSourceLocation( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(oratext *)
full path of input source [in compiler encoding]
Test if an element has attributes. Returns TRUE
if any attributes of any sort are defined (namespace or regular).
Syntax
boolean XmlDomHasAttrs( xmlctx *xctx, xmlelemnode *elem);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
XML element node |
Returns
(boolean)
TRUE
if element has attributes
Test if a node has children. Only Element
, Document
, DTD, and DocumentFragment
nodes may have children. Note that just because XmlDomGetChildNodes
returns a list does not mean the node actually has children, since the list may be empty, so a non-NULL
return from XmlDomGetChildNodes
should not be used as a test.
Syntax
boolean XmlDomHasChildNodes( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(boolean)
TRUE
if the node has any children
Inserts the node newChild
before the existing child node refChild
in the parent node. If refChild
is NULL
, appends to parent's children as for each XmlDomAppendChild
; otherwise it must be a child of the given parent. If newChild
is a DocumentFragment
, all of its children are inserted (in the same order) before refChild
; the DocumentFragment
node itself is not. If newChild
is already in the DOM tree, it is first removed from its current position.
Syntax
xmlnode* XmlDomInsertBefore( xmlctx *xctx, xmlnode *parent, xmlnode *newChild, xmlnode *refChild);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
parent |
IN |
parent that receives a new child |
newChild |
IN |
node to insert |
refChild |
IN |
reference node |
Returns
(xmlnode *)
node being inserted
Normalizes the subtree rooted at an element, merges adjacent Text
nodes children of elements. Note that adjacent Text
nodes will never be created during a normal parse, only after manipulation of the document with DOM calls.
Syntax
void XmlDomNormalize( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns the number of attributes of an element. Note that just because a list is returned by XmlDomGetAttrs
does not mean it contains any attributes; it may be an empty list with zero length.
Syntax
ub4 XmlDomNumAttrs( xmlctx *xctx, xmlelemnode *elem);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
elem |
IN |
XML element node |
Returns
(ub4)
number of attributes of node
Returns the number of children of a node. Only Element
, Document
, DTD, and DocumentFragment
nodes may have children, all other types return 0. Note that just because XmlDomGetChildNodes
returns a list does not mean that it contains any children; it may be an empty list with zero length.
Syntax
ub4 XmlDomNumChildNodes( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
Returns
(ub4)
number of children of node
Given a namespace prefix and a node, returns the namespace URI mapped to that prefix. If the given node doesn't have a matching prefix, its parent is tried, then its parent, and so on, all the way to the root node. If the prefix is undefined, NULL
is returned.
Syntax
oratext* XmlDomPrefixToURI( xmlctx *xctx, xmlnode *node, oratext *prefix);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
prefix |
IN |
prefix to map |
Returns
(oratext *)
URI for prefix [data encoding; NULL
if no match]
Removes a node from its parent's list of children and returns it. The node is orphaned; its parent will be NULL
after removal.
Syntax
xmlnode* XmlDomRemoveChild( xmlctx *xctx, xmlnode *oldChild);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
oldChild |
IN |
node to remove |
Returns
(xmlnode *)
node removed
Replaces the child node oldChild
with the new node newChild
in oldChild
's parent, and returns oldChild
(which is now orphaned, with a NULL
parent). If newChild
is a DocumentFragment
, all of its children are inserted in place of oldChild
; the DocumentFragment
node itself is not. If newChild
is already in the DOM tree, it is first removed from its current position.
Syntax
xmlnode* XmlDomReplaceChild( xmlctx *xctx, xmlnode *newChild, xmlnode *oldChild);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
newChild |
IN |
new node that is substituted |
oldChild |
IN |
old node that is replaced |
Returns
(xmlnode *)
node replaced
Set the default namespace for a node
Syntax
void XmlDomSetDefaultNS( xmlctx *xctx, xmlnode *node, oratext *defns);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
element or attribute DOM node |
defns |
IN |
new default namespace for the node |
Sets the namespace prefix of node (as NULL
-terminated string). Does not verify the prefix is defined. Just causes a new qualified name to be formed from the new prefix and the old local name; the new qualified name will be under DOM control and should not be managed by the user.
Syntax
void XmlDomSetNodePrefix( xmlctx *xctx, xmlnode *node, oratext *prefix);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
prefix |
OUT |
new namespace prefix |
Sets a node's value (character data) as a NULL
-terminated string. Does not allow setting the value to NULL
. Only Attr
, CDATA
, Comment
, PI and Text
nodes have values; trying to set the value of another type of node is a no-op. The new value must be in the data encoding. It is not verified, converted, or checked.
The value is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.
Syntax
xmlerr XmlDomSetNodeValue( xmlctx *xctx, xmlnode *node, oratext *value);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
value |
IN |
node's new value; data encoding; user control |
Returns
(xmlerr)
numeric error code, 0
on success
Sets the value (associated character data) for a node as a length-encoded string.
A NULL
-terminated version is available as XmlDomSetNodeValue
which takes the node value as a NULL
-terminated string. If the backing store is known to be XMLType
, then the node's data will be stored internally as length-encoded. Using the length-based Set functions will avoid having to copy and NULL
-terminate the data.
Syntax
xmlerr XmlDomSetNodeValueLen( xmlctx *xctx, xmlnode *node, oratext *value, ub4 len);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
value |
IN |
node's new value; data encoding; user control |
len |
IN |
length of value, in bytes |
Returns
(xmlerr)
numeric error code, 0
on success
Sets the large "value" (character data) for a node piecemeal from an input stream. For very large values, it is not always possible to store them [efficiently] as a single contiguous chunk. This function is used to store chunked data of that type. Used only for XMLType
data; XDK's data is always contiguous.
Syntax
xmlerr XmlDomSetNodeValueStream( xmlctx *xctx, xmlnode *node, xmlistream *istream);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
XML node |
istream |
IN |
input stream object |
Returns
(xmlerr)
numeric error code, 0
on success
Given a root node, validates it against the current DTD.
Syntax
xmlerr XmlDomValidate( xmlctx *xctx, xmlnode *node);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
node |
IN |
node to validate |
Returns
(xmlerr)
error code, XMLERR_OK [0]
means node is valid
Table 3-9 summarizes the methods of available through the NodeList
interface.
Table 3-9 Summary of NodeList Methods; DOM Package
Function | Summary |
---|---|
XmlDomFreeNodeList() | Free a node list returned by XmlDomGetElemsByTag, and so on. |
XmlDomGetNodeListItem() | Return nth node in list. |
XmlDomGetNodeListLength() | Return length of node list. |
Free a node list returned by XmlDomGetElemsByTag
or related functions, releasing all resources associated with it. If given a node list that is part of the DOM proper (such as the children of a node), does nothing.
Syntax
void XmlDomFreeNodeList( xmlctx *xctx, xmlnodelist *list);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
list |
IN |
NodeList to free |
Return nth node in a node list. The first item is index 0
.
Syntax
xmlnode* XmlDomGetNodeListItem( xmlctx *xctx, xmlnodelist *list, ub4 index);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
list |
IN |
NodeList |
index |
IN |
index into list |
Returns
(xmlnode *)
node at the nth position in node list [or NULL
]
Returns the number of nodes in a node list (its length). Note that nodes are referred to by index, so the range of valid indexes is 0
through length-1
.
Syntax
ub4 XmlDomGetNodeListLength( xmlctx *xctx, xmlnodelist *list);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
list |
IN |
NodeList |
Returns
(ub4)
number of nodes in node list
Table 3-10 summarizes the methods of available through the Notation
interface.
Table 3-10 Summary of NodeList Methods; DOM Package
Function | Summary |
---|---|
XmlDomGetNotationPubID() | Get notation's public ID |
XmlDomGetNotationSysID() | Get notation's system ID. |
Return a notation's public identifier (in the data encoding).
Syntax
oratext* XmlDomGetNotationPubID( xmlctx *xctx, xmlnotenode *note);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
note |
IN |
Notation node |
Returns
(oratext *)
notation's public identifier [data encoding; may be NULL
]
Return a notation's system identifier (in the data encoding).
Syntax
oratext* XmlDomGetNotationSysID( xmlctx *xctx, xmlnotenode *note);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
note |
IN |
Notation node |
Returns
(oratext *)
notation's system identifier [data encoding; may be NULL
]
Table 3-11 summarizes the methods of available through the ProcessingInstruction
interface.
Table 3-11 Summary of ProcessingInstruction Methods; DOM Package
Function | Summary |
---|---|
XmlDomGetPIData() | Get processing instruction's data. |
XmlDomGetPITarget() | Get PI's target. |
XmlDomSetPIData() | Set processing instruction's data. |
Returns the content (data) of a processing instruction (in the data encoding). If the node is not a ProcessingInstruction
, returns NULL
. The content is the part from the first non-whitespace character after the target until the ending "?>
".
Syntax
oratext* XmlDomGetPIData( xmlctx *xctx, xmlpinode *pi);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
pi |
IN |
ProcessingInstruction node |
Returns
(oratext *)
processing instruction's data [data encoding]
Returns a processing instruction's target string. If the node is not a ProcessingInstruction
, returns NULL
. The target is the first token following the markup that begins the ProcessingInstruction
. All ProcessingInstruction
s must have a target, though the data part is optional.
Syntax
oratext* XmlDomGetPITarget( xmlctx *xctx, xmlpinode *pi);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
pi |
IN |
ProcessingInstruction node |
Returns
(oratext *)
processing instruction's target [data encoding]
Sets a ProcessingInstruction
's content, which must be in the data encoding. It is not permitted to set the data to NULL
. If the node is not a ProcessingInstruction
, does nothing. The new data is not verified, converted, or checked.
Syntax
void XmlDomSetPIData( xmlctx *xctx, xmlpinode *pi, oratext *data);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
pi |
IN |
ProcessingInstruction node |
data |
IN |
ProcessingInstruction 's new data; data encoding |
Table 3-12 summarizes the methods of available through the Text
interface.
Table 3-12 Summary of Text Methods; DOM Package
Function | Summary |
---|---|
XmlDomSplitText() | Split text node in to two. |
Splits a single text node into two text nodes; the original data is split between them. If the given node is not type text, or the offset is outside of the original data, does nothing and returns NULL
. The offset is zero-based, and is in characters, not bytes. The original node is retained, its data is just truncated. A new text node is created which contains the remainder of the original data, and is inserted as the next sibling of the original. The new text node is returned.
Syntax
xmltextnode* XmlDomSplitText( xmlctx *xctx, xmltextnode *textnode, ub4 offset);
Parameter | In/Out | Description |
---|---|---|
xctx |
IN |
XML context |
textnode |
IN |
Text node |
offset |
IN |
0 -based character count at which to split text |
Returns
(xmltextnode *)
new text node