Element Interface

Table 4-5 summarizes the methods of available through the Element Interface.

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

XmlDomGetAttr

Returns the value of an element's attribute (specified by name). Note that an attribute may have the empty string as its value, but cannot be NULL. If the element does not have an attribute with the given name, NULL is returned.

Syntax

oratext* XmlDomGetAttr(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name)

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]

XmlDomGetAttrNS

Returns the value of an element's attribute (specified by URI and local name). Note that an attribute may have the empty string as its value, but cannot be NULL. If the element does not have an attribute with the given name, NULL is returned.

Syntax

oratext* XmlDomGetAttrNS(
   xmlctx *xctx,
   xmlelemnode *elem, 
   oratext *uri,
   oratext *local)

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]

XmlDomGetAttrNode

Returns an element's attribute specified by name. If the node is not an element or the named attribute does not exist, returns NULL.

Syntax

xmlattrnode* XmlDomGetAttrNode(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name)

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]

See Also:

XmlDomGetAttrNodeNS, XmlDomGetAttr

XmlDomGetAttrNodeNS

Returns an element's attribute specified by URI and localname. If the node is not an element or the named attribute does not exist, returns NULL.

Syntax

xmlattrnode* XmlDomGetAttrNodeNS(
   xmlctx *xctx,
   xmlelemnode *elem, 
   oratext *uri,
   oratext *local)

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]

See Also:

XmlDomGetAttrNode, XmlDomGetAttr

XmlDomGetChildrenByTag

Returns a list of children of an element with the given tag name, in the order in which they would be encountered in a preorder traversal of the tree. The tag name should be in the data encoding. The special name "*" matches all tag names; a NULL name matches nothing. Note that tag names are case sensitive. This function is not namespace aware; the full tag names are compared. If two prefixes which map to the same URI are compared, the comparison will fail. See XmlDomGetChildrenByTagNS for the namespace-aware version. The returned list can be freed with XmlDomFreeNodeList.

Syntax

xmlnodelist* XmlDomGetChildrenByTag(
   xmlctx *xctx, 
   xmlelemnode *elem,
   oratext *name)

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

XmlDomGetChildrenByTagNS

Returns a list of children of an element with the given URI and local name, in the order in which they would be encountered in a preorder traversal of the tree. The URI and local name should be in the data encoding. The special name "*" matches all URIs or tag names; a NULL name matches nothing. Note that names are case sensitive. See XmlDomGetChildrenByTag for the non-namespace version. The returned list can be freed with XmlDomFreeNodeList.

Syntax

xmlnodelist* XmlDomGetChildrenByTagNS(
   xmlctx *xctx,
   xmlelemnode *elem, 
   oratext *uri,
   oratext *local)

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

XmlDomGetElemsByTag

Returns a list of all elements (in the document tree rooted at the root node) with a given tag name, in the order in which they would be encountered in a preorder traversal of the tree. If root is NULL, the entire document is searched. The tag name should be in the data encoding. The special name "*" matches all tag names; a NULL name matches nothing. Note that tag names are case sensitive. This function is not namespace aware; the full tag names are compared. If two prefixes which map to the same URI are compared, the comparison will fail. See XmlDomGetElemsByTagNS for the namespace-aware version. The returned list can be freed with XmlDomFreeNodeList.

Syntax

xmlnodelist* XmlDomGetElemsByTag(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name)

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

XmlDomGetElemsByTagNS

Returns a list of all elements (in the document tree rooted at the root node) with a given URI and localname, in the order in which they would be encountered in a preorder traversal of the tree. If root is NULL, the entire document is searched. The tag name should be in the data encoding. The special name "**" matches all tag names; a NULL name matches nothing. Note that tag names are case sensitive. This function is not namespace aware; the full tag names are compared. If two prefixes which map to the same URI are compared, the comparison will fail. The returned list can be freed with XmlDomFreeNodeList.

Syntax

xmlnodelist* XmlDomGetElemsByTagNS(
   xmlctx *xctx,
   xmlelemnode *elem, 
   oratext *uri,
   oratext *local)

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

XmlDomGetTag

Returns the tagName} of a node, which is the same as its name. DOM 1.0 states "...even though there is a generic nodeName attribute on the Node interface, there is still a tagName attribute on the Element interface; these two attributes must contain the same value, but the Working Group considers it worthwhile to support both, given the different constituencies the DOM API must satisfy."

Syntax

oratext* XmlDomGetTag(
   xmlctx *xctx,
   xmlelemnode *elem)

Parameter	In/Out	Description
xctx	IN	XML context
elem	IN	`Element` node

Returns

(oratext *) element's name [data encoding]

See Also:

XmlDomGetNodeName

XmlDomHasAttr

Determines if an element has an attribute with the given name. Returns TRUE if so, FALSE if not.

Syntax

boolean XmlDomHasAttr(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name)

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

See Also:

XmlDomHasAttrNS

Determines if an element has an attribute with the given URI and localname. Returns TRUE if so, FALSE if not.

Syntax

boolean XmlDomHasAttrNS(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *uri,
   oratext *local)

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

See Also:

XmlDomHasAttr

XmlDomRemoveAttr

Removes an attribute (specified by name). If the removed attribute has a default value it is immediately re-created with that default. Note that the attribute is removed from the element's list of attributes, but the attribute node itself is not destroyed.

Syntax

void XmlDomRemoveAttr(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name)

Parameter	In/Out	Description
xctx	IN	XML context
elem	IN	element node
name	IN	attribute's name; data encoding

XmlDomRemoveAttrNS

Removes an attribute (specified by URI and local name). If the removed attribute has a default value it is immediately re-created with that default. Note that the attribute is removed from the element's list of attributes, but the attribute node itself is not destroyed.

Syntax

void XmlDomRemoveAttrNS(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *uri,
   oratext *local)

Parameter	In/Out	Description
xctx	IN	XML context
elem	IN	element node
uri	IN	attribute's namespace URI
local	IN	attribute's local name

See Also:

XmlDomRemoveAttr, XmlDomRemoveAttrNode

XmlDomRemoveAttrNode

Removes an attribute from an element. If the attribute has a default value, it is immediately re-created with that value (Specified set to FALSE). Returns the removed attribute on success, else NULL.

Syntax

xmlattrnode* XmlDomRemoveAttrNode(
   xmlctx *xctx,
   xmlelemnode *elem,
   xmlattrnode *oldAttr)

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]

See Also:

XmlDomRemoveAttr

XmlDomSetAttr

Creates a new attribute for an element with the given name and value (which should be in the data encoding). If the named attribute already exists, its value is simply replaced. The name and value are not verified, converted, or checked. The value is not parsed, so entity references will not be expanded. The attribute's specified flag will be set.

Syntax

void XmlDomSetAttr(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name,
   oratext *value)

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

XmlDomSetAttrNS

Creates a new attribute for an element with the given URI, localname and value (which should be in the data encoding). If the named attribute already exists, its value is simply replaced. The name and value are not verified, converted, or checked.

The value is not parsed, so entity references will not be expanded.

The attribute's specified flag will be set.

Syntax

void XmlDomSetAttrNS(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *uri, 
   oratext *qname,
   oratext *value)

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

XmlDomSetAttrNode

Adds a new attribute to an element. If an attribute with the given name already exists, it is replaced and the old attribute returned through oldNode. If the attribute is new, it is added to the element's list and oldNode set to NULL.

Syntax

xmlattrnode* XmlDomSetAttrNode(
   xmlctx *xctx,
   xmlelemnode *elem,
   xmlattrnode *newAttr)

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)

XmlDomSetAttrNodeNS

Adds a new attribute to an element. If an attribute with newNode's URI and localname already exists, it is replaced and the old attribute returned through oldNode. If the attribute is new, it is added to the element's list and oldNode set to NULL.

Syntax

xmlattrnode* XmlDomSetAttrNodeNS(
   xmlctx *xctx,
   xmlelemnode *elem,
   xmlattrnode *newAttr)

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]