NAME

DOM_Node - the Document Object Model (DOM) DOM_Node interface

SYNOPSIS

#include <domc.h>

DOM_Node *DOM_Node_insertBefore(DOM_Node *this,
            DOM_Node *newChild,
            DOM_Node *refChild);


DOM_Node *DOM_Node_replaceChild(DOM_Node *this,
            DOM_Node *newChild,
            DOM_Node *oldChild);


DOM_Node *DOM_Node_removeChild(DOM_Node *this, DOM_Node *oldChild);


DOM_Node *DOM_Node_appendChild(DOM_Node *this, DOM_Node *newChild);


int DOM_Node_hasChildNodes(DOM_Node *this);


DOM_Node *DOM_Node_cloneNode(DOM_Node *this, int deep);


void DOM_Node_normalize(DOM_Node *this);

DESCRIPTION

Values of nodeName, nodeValue, and attributes according to node typeNode InterfacenodeNamenodeValuenodeType DOM_Attrnameofattributevalueofattribute DOM_ATTRIBUTE_NODE DOM_CDATASection#cdata-sectioncontentoftheCDATASection DOM_CDATA_SECTION_NODE DOM_Comment#commentcontentofthecomment DOM_COMMENT_NODE DOM_Document#document NULL DOM_DOCUMENT_NODE DOM_DocumentFragment#document-fragment NULL DOM_DOCUMENT_FRAGMENT_NODE DOM_DocumentTypedocumenttypename NULL DOM_DOCUMENT_TYPE_NODE DOM_Elementtagname NULL DOM_ELEMENT_NODE DOM_Entityentityname NULL DOM_ENTITY_NODE DOM_EntityReferencenameofentityreferenced NULL DOM_ENTITY_REFERENCE_NODE DOM_Notationnotationname NULL DOM_NOTATION_NODE DOM_ProcessingInstructiontargetcontentexcludingtarget DOM_PROCESSING_INSTRUCTION_NODE DOM_Text#textcontentofthetextnode DOM_TEXT_NODEThe DOM_Node type is the primary datatype of the Document Object Model. Most of the other DOM interfaces inherit this interface. All DOM_Nodes have nodeName, nodeValue, and nodeType members. The vaules of these members depends on the node type. For example the DOM_Element node has a nodeValue corresponding to the tag name and a NULL nodeValue.

Only the DOM_Element node type has attributes. All other node types have a NULL attributes member. Child nodes are accessable through the childNodes DOM_NodeList member and the firstChild, lastChild, previousSibling, and nextSibling members. Not all element types have child nodes.

In DOMC node inheritance is emulated with simple typedef statements and a union that contains all possible subclass attributes. To access a child interface specific attribute it may be necessary to access it through this union. For example the systemId of a notation node is currently only accessible through the union like:

DOM_String *sysid;
sysid = node->u.Notation.systemId;

Care must be taken when modifing these union members (this is not well defined yet). Attributes accessible through the union that may need to be modified have helper methods to make this less awkward. The DOM_Node_setNodeValue function must be used to set the nodeValue member.Functions to get and set certain node members DOM_Node_getNodeValueget nodeValue attribute DOM_Node_setNodeValueset nodeValue and corresponding value in child interface DOM_Document_getDoctypegetthe doctype node of the document DOM_Document_getDocumentElementgetthe documentElement of the document DOM_CharacterData_getLengthgetthe length of a DOM_Text, DOM_Comment, DOM_CDATASection, or DOM_ProcessingInstruction

The all-important DOM_Node structure follows although some fields are left out in the interest of brevity. It may be necessary to look at this structure in the domc.h header.

struct DOM_Node {
	DOM_String *nodeName;
	DOM_String *nodeValue;
	unsigned short nodeType;
	DOM_Node *parentNode;
	DOM_NodeList *childNodes;
	DOM_Node *firstChild;
	DOM_Node *lastChild;
	DOM_Node *previousSibling;
	DOM_Node *nextSibling;
	DOM_NamedNodeMap *attributes;
	DOM_Document *ownerDocument;
	union {
		struct {
			DOM_DocumentType *doctype;
			DOM_Element *documentElement;
			DOM_String *version;
			DOM_String *encoding;
			int standalone;
		} Document;
		struct {
			DOM_NamedNodeMap *entities;
			DOM_NamedNodeMap *notations;
			DOM_String *publicId;
			DOM_String *systemId;
			DOM_String *internalSubset;
		} DocumentType;
		struct {
			int specified;
			DOM_Element *ownerElement;
		} Attr;
		struct {
			int length;
		} CharacterData;
		struct {
			DOM_String *publicId;
			DOM_String *systemId;
		} Notation;
		struct {
			DOM_String *publicId;
			DOM_String *systemId;
			DOM_String *notationName;
		} Entity;
		struct {
			DOM_String *target;
			DOM_String *data;
		} ProcessingInstruction;
	} u;
};

insertBefore: The DOM_Node_insertBefore function inserts the node newChild into this node directly before the existing child refChild. If refChild is a null pointer, newChild will be appended to the list. If newChild is a DOM_DocumentFragment node, all children are moved into this node in the same order before refChild. If newChild is already in the list it will first be removed.
replaceChild: Replaces the child node oldChild with newChild in the list of children, and returns the oldChild node.
If newChild is a DocumentFragment object, oldChild is replaced by all of the DocumentFragment children, which are inserted in the same order. If the newChild is already in the tree, it is first removed.
removeChild: Removes the child node indicated by oldChild from the list of children, and returns it.
appendChild: The DOM_Node_appendChild function appends newChild at the end of the childNodes list of this node. If newChild is already in the list, it is first removed.
hasChildNodes: The DOM_Node_hasChildNodes function returns 1 if this node contains children and 0 if this node does not support child nodes or currently does not have any child nodes.
cloneNode: The DOM_Node_cloneNode function creates a copy of this node. If the deep parameter is not 0 all children will be cloned as well. The cloned node's parentNode pointer is NULL. Cloning a DOM_Element node copies all attributes regardless of what the deep parameter is. It is possibly to clone every node type with DOMC whereas the W3C specifications do not require cloning DOM_Document, DOM_DocumentType, DOM_Entity, and DOM_Notation nodes.
The DOM specification requires that cloning an attribute node directly will return a specified attribute opposed to an attribute resulting from a default value specified in the DTD. Currently DOMC does not consider DTD default values. The value of attr->u.Attr.specified will always be 0.
normalize: The DOM_Node_normalize function merges adjecent DOM_Text node content into "normal" form in the subtree of this node. Empty DOM_Text nodes will also be removed. When a document is first loaded it is in "normal" form.

RETURNS

insertBefore: The DOM_Node_insertBefore function returns a pointer to the node that was inserted.
replaceChild: The node replaced.
removeChild: The node removed.
appendChild: The DOM_Node_appendChild function returns a pointer to newChild or a null pointer if the operation failed in which case DOM_Exception will be set appropriately.
cloneNode: The DOM_Node_cloneNode function returns the new cloned node or a null pointer if the operation failed in whhich case DOM_Exception will be set appropriately.