DOM_Node

3. DOM_Node

**Table 1. Values of nodeName, nodeValue, and attributes according to node type**
Node Interface	nodeName	nodeValue	nodeType
`DOM_Attr`	name of attribute	value of attribute	`DOM_ATTRIBUTE_NODE`
`DOM_CDATASection`	`"#cdata-section"`	content of the CDATA Section	`DOM_CDATA_SECTION_NODE`
`DOM_Comment`	`"#comment"`	content of the comment	`DOM_COMMENT_NODE`
`DOM_Document`	`"#document"`	`NULL`	`DOM_DOCUMENT_NODE`
`DOM_DocumentFragment`	`"#document-fragment"`	`NULL`	`DOM_DOCUMENT_FRAGMENT_NODE`
`DOM_DocumentType`	document type name	`NULL`	`DOM_DOCUMENT_TYPE_NODE`
`DOM_Element`	tag name	`NULL`	`DOM_ELEMENT_NODE`
`DOM_Entity`	entity name	`NULL`	`DOM_ENTITY_NODE`
`DOM_EntityReference`	name of entity referenced	`NULL`	`DOM_ENTITY_REFERENCE_NODE`
`DOM_Notation`	notation name	`NULL`	`DOM_NOTATION_NODE`
`DOM_ProcessingInstruction`	target	content excluding target	`DOM_PROCESSING_INSTRUCTION_NODE`
`DOM_Text`	`"#text"`	content of the text node	`DOM_TEXT_NODE`

The 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.

**Table 2. Functions to get and set certain node members**
`DOM_Node_getNodeValue`	get `nodeValue` attribute
`DOM_Node_setNodeValue`	set `nodeValue` and corresponding value in child interface
`DOM_Document_getDoctype`	get the `doctype` node of the document
`DOM_Document_getDocumentElement`	get the `documentElement` of the document
`DOM_CharacterData_getLength`	get the `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;
  };

3.1. The DOM_Node functions

The DOM_Node_insertBefore function
Synopsis


  #include <domc.h>
  DOM_Node *DOM_Node_insertBefore(DOM_Node *this,
           DOM_Node *newChild,
           DOM_Node *refChild);

Description
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.
Returns
The DOM_Node_insertBefore function returns a pointer to the node that was inserted.

The DOM_Node_replaceChild function
Synopsis


  #include <domc.h>
  DOM_Node *DOM_Node_replaceChild(DOM_Node *this,
           DOM_Node *newChild,
           DOM_Node *oldChild);

Description
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.
Returns
The node replaced.

The DOM_Node_removeChild function
Synopsis


  #include <domc.h>
  DOM_Node *DOM_Node_removeChild(DOM_Node *this, DOM_Node *oldChild);

Description
Removes the child node indicated by oldChild from the list of children, and returns it.
Returns
The node removed.

The DOM_Node_appendChild function
Synopsis


  #include <domc.h>
  DOM_Node *DOM_Node_appendChild(DOM_Node *this, DOM_Node *newChild);

Description
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.
Returns
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.

The DOM_Node_hasChildNodes function
Synopsis


  #include <domc.h>
  int DOM_Node_hasChildNodes(DOM_Node *this);

Description
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.

The DOM_Node_cloneNode function
Synopsis


  #include <domc.h>
  DOM_Node *DOM_Node_cloneNode(DOM_Node *this, int deep);

Description
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.
Returns
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.

The DOM_Node_normalize function
Synopsis


  #include <domc.h>
  void DOM_Node_normalize(DOM_Node *this);

Description
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.