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