DOM_Document

## 2. DOM_Document

A `DOM_Document` represents an entire XML document and acts as the root of the DOM tree. Because nodes cannot exist outside of the context of a `DOM_Document` this interface provides the factory methods needed to create individual nodes to compose and modify DOM trees. The `ownerDocument` member of a `DOM_Node` points to the document from which it was created (except `DOM_DocumentType` and `DOM_Document` which may have a NULL `ownerDocument` member). This interface also provides the `DOM_Document_getElementsByTagName` function for retriving all elements with a specified name.

To build a document from scratch use the expression `DOM_Implementation_createDocument(NULL, NULL, NULL)` to create an empty document and add new nodes using `DOM_Document_createElement`, `DOM_Document_createComment`, etc with `DOM_Node_appendChild`, `DOM_Node_insertBefore` or similar. See the `DOM_Implementation` and `DOM_Node` interface documentation for details.

Memory Management

The `DOM_DocumentLS_load`, `DOM_DocumentLS_read`, and `DOM_Document_createXxx` functions allocate memory that must at some point be freed with `DOM_Document_destoryNode`. The `DOM_Document_destroyNode` function may be used to released nodes of all types such as `DOM_Element`, `DOM_Text`, `DOM_Attr`, `DOM_Document`. All children of a node are freed when the parent is freed. An entire document may be free with the expression `DOM_Document_destroyNode(doc, doc)`. Beware that freeing a node that is still a decendant of another node will result in a tree with invalid pointers and will cause the program to crash when freed again. There are only two other special cases to consider. First, the `DOM_Document_destroyNodeList` function must be called for each `DOM_NodeList` returned by `DOM_Element_getElementsByTagName` and `DOM_Document_getElementsByTagName`. Second, the `DOM_DocumentFragment` node cannot be a child of another node. When added to the tree, it's children are actually moved into the target node leaving an empty `DOM_DocumentFragment`. This empty node must be freed with `DOM_Document_destroyNode` if it will no longer be used. For completeness, the `DOM_DocumentEvent_destroyEvent` function must be called to free `DOM_Event` objects however that non-core API is not yet documented here.

### 2.1. The DOM_DocumentLS functions

These functions are used to load and store DOM trees from and to XML. Currently the Expat XML parser is used to parse XML. These functions are specific to DOMC.

The `DOM_DocumentLS_load` function
Synopsis

      #include <domc.h>
      int DOM_DocumentLS_load(DOM_DocumentLS *this, const char *uri);

Description
The `DOM_DocumentLS_load` function builds a DOM tree from the complete well formed XML document specified by the `uri` parameter.
Returns
The `DOM_DocumentLS_load` function returns 0 if the file was successfully loaded. Otherwise -1 is returned and `DOM_Exception` is set appropriately.

The `DOM_DocumentLS_save` function
Synopsis

      #include <domc.h>
      int DOM_DocumentLS_save(DOM_DocumentLS *this, const char *uri, const DOM_Node *node);

Description
The `DOM_DocumentLS_save` function serializes the `DOM_DocumentLS` object to a file specified by the `uri` parameter. Normally this object is a complete `DOM_Document` node however any `DOM_Node` type such as a `DOM_Element` will be accepted (although only a complete well formed XML document may be loaded).
Returns
The `DOM_DocumentLS_save` function returns 0 if the file was successfully saved. Otherwise -1 is returned and `DOM_Exception` is set appropriately.

The `DOM_DocumentLS_fread` function
Synopsis

      #include <domc.h>
      int DOM_DocumentLS_fread(DOM_DocumentLS *this, FILE *stream);

Description
The `DOM_DocumentLS_fread` function builds a DOM tree from the complete well formed XML document read from the stream specified by the `stream` parameter.
Returns
The `DOM_DocumentLS_fread` function returns 0 if complete XML document was successfully read. Otherwise -1 is returned and `DOM_Exception` is set appropriately.

The `DOM_DocumentLS_fwrite` function
Synopsis

      #include <domc.h>
      int DOM_DocumentLS_fwrite(const DOM_DocumentLS *this, FILE *stream);

Description
The `DOM_DocumentLS_fwrite` function serializes the `DOM_DocumentLS` object to the stream specified by the `stream` parameter. Normally this object is a complete `DOM_Document` node however any `DOM_Node` type such as a `DOM_Element` will be accepted (although only a complete well formed XML document may be read).
Returns
The `DOM_DocumentLS_fwrite` function returns 0 if the node was successfully written. Otherwise -1 is returned and `DOM_Exception` is set appropriately.

### 2.2. The DOM_Document functions

These functions are used to create and destroy nodes of a document, retrieve all elements from a document by name, or access the `documentElement` of a `DOM_Document` object.

The `DOM_Document_getDocumentElement` function
Synopsis

      #include <domc.h>
      DOM_Element *DOM_Document_getDocumentElement(DOM_Document *doc);

Description
Returns the root element of the document tree. The root element is also accessable through the `childNodes` `DOM_NodeList` member however the children of a `DOM_Document` may also be processing instructions, document type nodes, and comments which may preceed the document element in the list. Therefore this function is provied as a convienience.

The `DOM_Document_destroyNode` function
Synopsis

      #include <domc.h>
      void DOM_Document_destroyNode(DOM_Document *doc, DOM_Node *node);

Description
The `DOM_Document_destroyNode` function frees the node `node` as well as it's children if any. An entire DOM tree may be freed using the expression `DOM_Document_destroyNode(doc, doc)`. See the section above entitled Memory Management.

The `DOM_Document_destroyNodeList` function
Synopsis

      #include <domc.h>
      void DOM_Document_destroyNodeList(DOM_Document *doc, DOM_NodeList *nl, int free_nodes);

Description
The `DOM_Document_destroyNodeList` function frees the `DOM_NodeList` object `nl`. The `free_nodes` parameter should be 0 indicating that nodes in the list should not be freed as they are almost certainly members of a DOM tree and will be freed when the tree is freed. This function must be called for each list returned by the `DOM_Element_getElementsByTagName` and `DOM_Document_getElementsByTagName` functions.

The `DOM_Document_createElement` function
Synopsis

      #include <domc.h>
      DOM_Element *DOM_Document_createElement(DOM_Document *this, DOM_String *tagName);

Description
Create a `DOM_Element` object with the name `tagName` with no children.

Note: currently DOMC does not populate default attributes specified in a DTD as it should.
Returns
The new `DOM_Element` object or NULL if the operation failed in which case `DOM_Exception` will be set appropriately.

The `DOM_Document_createDocumentFragment` function
Synopsis

      #include <domc.h>
      DOM_DocumentFragment *DOM_Document_createDocumentFragment(DOM_Document *this);

Description
Create an empty `DOM_DocumentFragment` object into which other nodes may be placed. Subsequently inserting or appending a `DOM_DocumentFragment` into another node will move all of the fragments children into the target node. After doing this an empty `DOM_DocumentFragment` object is left behind and must be freed with `DOM_Document_destroyNode` if it will not be used again.
Returns
An empty `DOM_DocumentFragment` object or NULL if the operation failed in which case `DOM_Exception` will be set appropriately.

The `DOM_Document_createTextNode` function
Synopsis

      #include <domc.h>
      DOM_Text *DOM_Document_createTextNode(DOM_Document *this, DOM_String *data);

Description
Creates a `DOM_Text` node given the specified string represented by the `data` parameter.
Returns
The new `DOM_Text` object or NULL of the operation failed in which case `DOM_Exception` will be set appropriately.

The `DOM_Document_createComment` function
Synopsis

      #include <domc.h>
      DOM_Comment *DOM_Document_createComment(DOM_Document *this, DOM_String *data);

Description
Creates a `DOM_Comment` node with the specified `data` parameter. The '<--' and '-->' comment delimiters are not part of the comment and should not be included in the `data` string.
Returns
The new `DOM_Comment` object or NULL of the operation failed in which case `DOM_Exception` will be set appropriately.

The `DOM_Document_createCDATASection` function
Synopsis

      #include <domc.h>
      DOM_CDATASection *DOM_Document_createCDATASection(DOM_Document *this, DOM_String *data);

Description
Creates a `DOM_CDATASection` node from the specified string `data`. Only the text inside the '<[[' and ']]>' brackets consititute the CDATA section content.
Returns
The new `DOM_CDATASection` object or NULL of the operation failed in which case `DOM_Exception` is set appropriately.

The `DOM_Document_createProcessingInstruction` function
Synopsis

      #include <domc.h>
      DOM_ProcessingInstruction *DOM_Document_createProcessingInstruction(DOM_Document *this,
               DOM_String *target,
               DOM_String *data);

Description
Creates a `DOM_ProcessingInstruction` node given the specified `target` and `data` string parameters. The '<?' and '?>' processing instruction delimiters are not part of the `data` string.
Returns
The new `DOM_ProcessingInstruction` object or NULL of the operation failed in which case `DOM_Exception` will be set appropriately.

The `DOM_Document_createAttribute` function
Synopsis

      #include <domc.h>
      DOM_Attr *DOM_Document_createAttribute(DOM_Document *this, DOM_String *name);

Description
Creates a `DOM_Attr` with the given `name` parameter. The `DOM_Attr` object may then be assigned to a `DOM_Element` using the `DOM_Element_setAttributeNode` function. All attributes of an element will be freed if the element is freed.
Returns
The new `DOM_Attr` object or NULL of the operation failed in which case `DOM_Exception` will be set appropriately.

The `DOM_Document_createEntityReference` function
Synopsis

      #include <domc.h>
      DOM_EntityReference *DOM_Document_createEntityReference(DOM_Document *this, DOM_String *name);

Description
Creates a `DOM_EntityReference` object.

Note: currently DOMC does not resolve entities, meaning the child list of a `DOM_EntityReference` will not be populated if the entity is known as it would in a full featured DOM implementation.
Returns
The new `DOM_EntityReference` object or NULL of the operation failed in which case `DOM_Exception` will be set appropriately.

The `DOM_Document_getElementsByTagName` function
Synopsis

      #include <domc.h>
      DOM_NodeList *DOM_Document_getElementsByTagName(DOM_Document *this, DOM_String *tagname);

Description
The `DOM_Document_getElementsByTagName` function performs a preorder traversal of the entire document and returns a `DOM_NodeList` of the elements with the name `tagname` in the order in which they were encountered.

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).
Returns
A new `DOM_NodeList` object containing pointers to the matching `DOM_Element`s.

Copyright 2003 Michael B. Allen <mballen@erols.com> Generated by CStyleX 0.1.1