DOM_Document(3m)

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.