NAME

DOM_Document - the Document Object Model (DOM) DOM_Document interface

SYNOPSIS

#include <domc.h>

int DOM_DocumentLS_load(DOM_DocumentLS *this, const char *uri);


int DOM_DocumentLS_save(DOM_DocumentLS *this, const char *uri, const DOM_Node *node);


int DOM_DocumentLS_fread(DOM_DocumentLS *this, FILE *stream);


int DOM_DocumentLS_fwrite(const DOM_DocumentLS *this, FILE *stream);

DOM_Element *DOM_Document_getDocumentElement(DOM_Document *doc);


void DOM_Document_destroyNode(DOM_Document *doc, DOM_Node *node);


void DOM_Document_destroyNodeList(DOM_Document *doc, DOM_NodeList *nl, int free_nodes);


DOM_Element *DOM_Document_createElement(DOM_Document *this, DOM_String *tagName);


DOM_DocumentFragment *DOM_Document_createDocumentFragment(DOM_Document *this);


DOM_Text *DOM_Document_createTextNode(DOM_Document *this, DOM_String *data);


DOM_Comment *DOM_Document_createComment(DOM_Document *this, DOM_String *data);


DOM_CDATASection *DOM_Document_createCDATASection(DOM_Document *this, DOM_String *data);


DOM_ProcessingInstruction *DOM_Document_createProcessingInstruction(DOM_Document *this,
            DOM_String *target,
            DOM_String *data);


DOM_Attr *DOM_Document_createAttribute(DOM_Document *this, DOM_String *name);


DOM_EntityReference *DOM_Document_createEntityReference(DOM_Document *this, DOM_String *name);


DOM_NodeList *DOM_Document_getElementsByTagName(DOM_Document *this, DOM_String *tagname);

DESCRIPTION

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.

DOM_DocumentLS_load: The DOM_DocumentLS_load function builds a DOM tree from the complete well formed XML document specified by the uri parameter.
DOM_DocumentLS_save: 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).
DOM_DocumentLS_fread: 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.
DOM_DocumentLS_fwrite: 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).
getDocumentElement: 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.
destroyNode: 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 entitledMemory Management.
destroyNodeList: 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.
createElement: 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.
createDocumentFragment: 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.
createTextNode: Creates a DOM_Text node given the specified string represented by the data parameter.
createComment: 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.
createCDATASection: Creates a DOM_CDATASection node from the specified string data. Only the text inside the '<[[' and ']]>' brackets consititute the CDATA section content.
createProcessingInstruction: 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.
createAttribute: 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.
createEntityReference: 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.
getElementsByTagName: 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

createElement: The new DOM_Element object or NULL if the operation failed in which case DOM_Exception will be set appropriately.
createDocumentFragment: An empty DOM_DocumentFragment object or NULL if the operation failed in which case DOM_Exception will be set appropriately.
createTextNode: The new DOM_Text object or NULL of the operation failed in which case DOM_Exception will be set appropriately.
createComment: The new DOM_Comment object or NULL of the operation failed in which case DOM_Exception will be set appropriately.
createCDATASection: The new DOM_CDATASection object or NULL of the operation failed in which case DOM_Exception is set appropriately.
createProcessingInstruction: The new DOM_ProcessingInstruction object or NULL of the operation failed in which case DOM_Exception will be set appropriately.
createAttribute: The new DOM_Attr object or NULL of the operation failed in which case DOM_Exception will be set appropriately.
createEntityReference: The new DOM_EntityReference object or NULL of the operation failed in which case DOM_Exception will be set appropriately.
getElementsByTagName: A new DOM_NodeList object containing pointers to the matching DOM_Elements.