NAME

SYNOPSIS

#include <domc.h>

DOM_String *DOM_Element_getAttribute(DOM_Element *this, DOM_String *name);


void DOM_Element_setAttribute(DOM_Element *this,
            DOM_String *name,
            DOM_String *value);


void DOM_Element_removeAttribute(DOM_Element *this, DOM_String *name);


DOM_Attr *DOM_Element_getAttributeNode(DOM_Element *this, DOM_String *name);


DOM_Attr *DOM_Element_setAttributeNode(DOM_Element *this, DOM_Attr *newAttr);


DOM_Attr *DOM_Element_removeAttributeNode(DOM_Element *this, DOM_Attr *oldAttr);


DOM_NodeList *DOM_Element_getElementsByTagName(DOM_Element *this, DOM_String *name);


int DOM_Element_hasAttribute(DOM_Element *this, DOM_String *name);

DESCRIPTION

nodeName This DOM_String * corresponds to the tag name of the element. It is read-only and cannot be modified.

nodeValue This is always NULL

childNodes This DOM_NodeList * contains the child nodes of this element.

attributes This DOM_NamedNodeMap * contains the DOM_Attr attribute nodes of this element.

firstChild This DOM_Node * points to the first child of this element or NULL if the element currently has no children.

lastChild This DOM_Node * points to the last child of this element or NULL if the element currently has no children.

previousSibling This DOM_Node * points to the previous node in the childNodes list of the parent element of this element.

nextSibling This DOM_Node * points to the next node in the childNodes list of the parent element of this element.

In addition to the functions provided by the DOM_Node interface this interface provides additional functions mainly for manipulating attributes.

The DOM specifications require support for entity references which may result in the childNodes of an attribute containing a potentially complex subtree of DOM nodes. DOMC currently has very weak support for entity references and as a result attributes will never have children. The default module for loading and storing XML documents uses the Expat XML parser which expands entity references by default. Expat recently added support for parsing external entities but DOMC does not yet use this functionalty.

getAttribute

The DOM_Element_getAttribute function returns the nodeValue of the named attrbute or an empty string if this element does have an attribute by that name.

setAttribute

The DOM_Element_setAttribute method adds a new attribute or sets the nodeValue of an existing attribute. Take care not to pass markup characters in the name and value parameters. It will be accepted and the resulting serialized XML may be incorrect.

removeAttribute

The DOM_Element_removeAttribute function removes and frees the named attribute.

Note the W3C specifications require that an attribute with a default DTD value should automatically be repopulated if a user supplied attribute value is removed. DOMC does not support default DTD values. This function will simply remove the attribute regarless of whether or not the attribute value was specified in the DTD. The Expat XML parser just released support for parsing external entities. DOMC will likely support external entities and default attribute values in a future version.

getAttributeNode

The DOM_Element_getAttributeNode function returns the DOM_Attr * by name. If this element does not have an attibute with that name a null pointer is returned.

setAttributeNode

The DOM_Element_setAttributeNode function adds the attribute newAttr to the attributes of this element. If this element already has an attribute with the same name it will be replaced with the new attribute and returned.

removeAttributeNode

The DOM_Element_removeAttributeNode function removes and returns a pointer to the attribtue oldAttr.

DOMC does not support default DTD values. This function will remove an attribute regarless of whether or not a default attribute value was specified in the DTD.

getElementsByTagName

The DOM_Element_getElementsByTagName function allocates memory for a DOM_NodeList object, performs a preorder traversal of the subtree specified by this, and adds a pointer to the node list for each DOM_Element node with a nodeName that matches the name parameter. Because elements are added to the list as they are encountered during preoder traversal the effect is that elements will be listed in "document order".

After the DOM_NodeList object will no longer to be used it must be freed with the DOM_Document_destroyNodeList function with a free_nodes parameter of 0 (the nodes in this list should not be freed or all other references to them will be invalid).

hasAttribute

The DOM_Element_hasAttribute function returns 1 if this element has an attribute with the specified name or 0 if there is no such element.

RETURNS

setAttributeNode

The DOM_Element_setAttributeNode function returns the attribute being replaced if one with the same name already exists in the map. Otherwise a null pointer is returned.

getElementsByTagName

A new DOM_NodeList object containing pointers to the matching DOM_Elements.