<?xml version="1.0" encoding="utf-8"?>
<interface name="DOM_Document" short="the Document Object Model (DOM) DOM_Document interface">

<comments>
	Copyright 2003 Michael B. Allen &lt;mballen@erols.com&gt;
	Generated by CStyleX 0.1.1
</comments>

<include>domc.h</include>

<title>DOM_Document</title>

<desc>
A <tt>DOM_Document</tt> represents an entire XML document and acts as the root of the DOM tree. Because nodes cannot exist outside of the context of a <tt>DOM_Document</tt> this interface provides the factory methods needed to create individual nodes to compose and modify DOM trees. The <tt>ownerDocument</tt> member of a <tt>DOM_Node</tt> points to the document from which it was created (except <tt>DOM_DocumentType</tt> and <tt>DOM_Document</tt> which may have a NULL <tt>ownerDocument</tt> member). This interface also provides the <tt>DOM_Document_getElementsByTagName</tt> function for retriving all elements with a specified name.
<p/>
To build a document from scratch use the expression <tt>DOM_Implementation_createDocument(NULL, NULL, NULL)</tt> to create an empty document and add new nodes using <tt>DOM_Document_createElement</tt>, <tt>DOM_Document_createComment</tt>, etc with <tt>DOM_Node_appendChild</tt>, <tt>DOM_Node_insertBefore</tt> or similar. See the <tt>DOM_Implementation</tt> and <tt>DOM_Node</tt> interface documentation for details.
<p/>
<b>Memory Management</b>
<p/>
The <tt>DOM_DocumentLS_load</tt>, <tt>DOM_DocumentLS_read</tt>, and <tt>DOM_Document_createXxx</tt> functions allocate memory that must at some point be freed with <tt>DOM_Document_destoryNode</tt>.
The <tt>DOM_Document_destroyNode</tt> function may be used to released nodes of all types such as <tt>DOM_Element</tt>, <tt>DOM_Text</tt>, <tt>DOM_Attr</tt>, <tt>DOM_Document</tt>. All children of a node are freed when the parent is freed.
An entire document may be free with the expression <tt>DOM_Document_destroyNode(doc, doc)</tt>.
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 <tt>DOM_Document_destroyNodeList</tt> function must be called for each <tt>DOM_NodeList</tt> returned by <tt>DOM_Element_getElementsByTagName</tt> and <tt>DOM_Document_getElementsByTagName</tt>. Second, the <tt>DOM_DocumentFragment</tt> 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 <tt>DOM_DocumentFragment</tt>. This empty node must be freed with <tt>DOM_Document_destroyNode</tt> if it will no longer be used. For completeness, the <tt>DOM_DocumentEvent_destroyEvent</tt> function must be called to free <tt>DOM_Event</tt> objects however that non-core API is not yet documented here.
</desc>

<group>
<title>The DOM_DocumentLS functions</title>
<desc>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.</desc>

<func name="DOM_DocumentLS_load">
<pre>int DOM_DocumentLS_load(DOM_DocumentLS *this, const char *uri);</pre>
<param name="this"/>
<param name="uri"/>
<desc>
The <tt>DOM_DocumentLS_load</tt> function builds a DOM tree from the complete well formed XML document specified by the <tt>uri</tt> parameter.
</desc>
<ret>
The <tt>DOM_DocumentLS_load</tt> function returns 0 if the file was successfully loaded. Otherwise -1 is returned and <tt>DOM_Exception</tt> is set appropriately.
</ret>
</func>

<func name="DOM_DocumentLS_save">
<pre>int DOM_DocumentLS_save(DOM_DocumentLS *this, const char *uri, const DOM_Node *node);</pre>
<param name="this"/>
<param name="uri"/>
<param name="node"/>
<desc>
The <tt>DOM_DocumentLS_save</tt> function serializes the <tt>DOM_DocumentLS</tt> object to a file specified by the <tt>uri</tt> parameter. Normally this object is a complete <tt>DOM_Document</tt> node however any <tt>DOM_Node</tt> type such as a <tt>DOM_Element</tt> will be accepted (although only a complete well formed XML document may be loaded).
</desc>
<ret>
The <tt>DOM_DocumentLS_save</tt> function returns 0 if the file was successfully saved. Otherwise -1 is returned and <tt>DOM_Exception</tt> is set appropriately.
</ret>
</func>

<func name="DOM_DocumentLS_fread">
<pre>int DOM_DocumentLS_fread(DOM_DocumentLS *this, FILE *stream);</pre>
<param name="this"/>
<param name="stream"/>
<desc>
The <tt>DOM_DocumentLS_fread</tt> function builds a DOM tree from the complete well formed XML document read from the stream specified by the <tt>stream</tt> parameter.
</desc>
<ret>
The <tt>DOM_DocumentLS_fread</tt> function returns 0 if complete XML document was successfully read. Otherwise -1 is returned and <tt>DOM_Exception</tt> is set appropriately.
</ret>
</func>

<func name="DOM_DocumentLS_fwrite">
<pre>int DOM_DocumentLS_fwrite(const DOM_DocumentLS *this, FILE *stream);</pre>
<param name="this"/>
<param name="stream"/>
<desc>
The <tt>DOM_DocumentLS_fwrite</tt> function serializes the <tt>DOM_DocumentLS</tt> object to the stream specified by the <tt>stream</tt> parameter. Normally this object is a complete <tt>DOM_Document</tt> node however any <tt>DOM_Node</tt> type such as a <tt>DOM_Element</tt> will be accepted (although only a complete well formed XML document may be read).
</desc>
<ret>
The <tt>DOM_DocumentLS_fwrite</tt> function returns 0 if the node was successfully written. Otherwise -1 is returned and <tt>DOM_Exception</tt> is set appropriately.
</ret>
</func>

</group>

<group>
<title>The DOM_Document functions</title>
<desc>These functions are used to create and destroy nodes of a document, retrieve all elements from a document by name, or access the <tt>documentElement</tt> of a <tt>DOM_Document</tt> object.</desc>

<meth name="getDocumentElement">
<pre>DOM_Element *DOM_Document_getDocumentElement(DOM_Document *doc);</pre>
<param name="doc"/>
<desc>
Returns the root element of the document tree. The root element is also accessable through the <tt>childNodes</tt> <tt>DOM_NodeList</tt> member however the children of a <tt>DOM_Document</tt> 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.
</desc>
</meth>

<meth name="destroyNode">
<pre>void DOM_Document_destroyNode(DOM_Document *doc, DOM_Node *node);</pre>
<param name="doc"/>
<param name="node"/>
<desc>
The <tt>DOM_Document_destroyNode</tt> function frees the node <tt>node</tt> as well as it's children if any. An entire DOM tree may be freed using the expression <tt>DOM_Document_destroyNode(doc, doc)</tt>. See the section above entitled <i>Memory Management</i>.
</desc>
</meth>

<meth name="destroyNodeList">
<pre>void DOM_Document_destroyNodeList(DOM_Document *doc, DOM_NodeList *nl, int free_nodes);</pre>
<param name="doc"/>
<param name="nl"/>
<param name="free_nodes"/>
<desc>
The <tt>DOM_Document_destroyNodeList</tt> function frees the <tt>DOM_NodeList</tt> object <tt>nl</tt>. The <tt>free_nodes</tt> 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 <tt>DOM_Element_getElementsByTagName</tt> and <tt>DOM_Document_getElementsByTagName</tt> functions.
</desc>
</meth>

<meth name="createElement">
<pre>DOM_Element *DOM_Document_createElement(DOM_Document *this, DOM_String *tagName);</pre>
<param name="this"/>
<param name="tagName"/>
<desc>
Create a <tt>DOM_Element</tt> object with the name <tt>tagName</tt> with no children.
<p/>
<i>Note: currently DOMC does not populate default attributes specified in a DTD as it should.</i>
</desc>
<ret>The new <tt>DOM_Element</tt> object or NULL if the operation failed in which case <tt>DOM_Exception</tt> will be set appropriately.</ret>
</meth>

<meth name="createDocumentFragment">
<pre>DOM_DocumentFragment *DOM_Document_createDocumentFragment(DOM_Document *this);</pre>
<param name="this"/>
<desc>
Create an empty <tt>DOM_DocumentFragment</tt> object into which other nodes may be placed. Subsequently inserting or appending a <tt>DOM_DocumentFragment</tt> into another node will move all of the fragments children into the target node. After doing this an empty <tt>DOM_DocumentFragment</tt> object is left behind and must be freed with <tt>DOM_Document_destroyNode</tt> if it will not be used again.
</desc>
<ret>An empty <tt>DOM_DocumentFragment</tt> object or NULL if the operation failed in which case <tt>DOM_Exception</tt> will be set appropriately.</ret>
</meth>

<meth name="createTextNode">
<pre>DOM_Text *DOM_Document_createTextNode(DOM_Document *this, DOM_String *data);</pre>
<param name="this"/>
<param name="data"/>
<desc>
Creates a <tt>DOM_Text</tt> node given the specified string represented by the <tt>data</tt> parameter.
</desc>
<ret>The new <tt>DOM_Text</tt> object or NULL of the operation failed in which case <tt>DOM_Exception</tt> will be set appropriately.</ret>
</meth>

<meth name="createComment">
<pre>DOM_Comment *DOM_Document_createComment(DOM_Document *this, DOM_String *data);</pre>
<param name="this"/>
<param name="data"/>
<desc>Creates a <tt>DOM_Comment</tt> node with the specified <tt>data</tt> parameter. The '&lt;--' and '--&gt;' comment delimiters are not part of the comment and should not be included in the <tt>data</tt> string.
</desc>
<ret>The new <tt>DOM_Comment</tt> object or NULL of the operation failed in which case <tt>DOM_Exception</tt> will be set appropriately.</ret>
</meth>

<meth name="createCDATASection">
<pre>DOM_CDATASection *DOM_Document_createCDATASection(DOM_Document *this, DOM_String *data);</pre>
<param name="this"/>
<param name="data"/>
<desc>
Creates a <tt>DOM_CDATASection</tt> node from the specified string <tt>data</tt>. Only the text inside the '&lt;[[' and ']]&gt;' brackets consititute the CDATA section content.
</desc>
<ret>The new <tt>DOM_CDATASection</tt> object or NULL of the operation failed in which case <tt>DOM_Exception</tt> is set appropriately.</ret>
</meth>

<meth name="createProcessingInstruction" wrap="true">
<pre>DOM_ProcessingInstruction *DOM_Document_createProcessingInstruction(DOM_Document *this, DOM_String *target, DOM_String *data);</pre>
<param name="this"/>
<param name="target"/>
<param name="data"/>
<desc>Creates a <tt>DOM_ProcessingInstruction</tt> node given the specified <tt>target</tt> and <tt>data</tt> string parameters. The '&lt;?' and '?&gt;' processing instruction delimiters are not part of the <tt>data</tt> string.
</desc>
<ret>The new <tt>DOM_ProcessingInstruction</tt> object or NULL of the operation failed in which case <tt>DOM_Exception</tt> will be set appropriately.</ret>
</meth>

<meth name="createAttribute">
<pre>DOM_Attr *DOM_Document_createAttribute(DOM_Document *this, DOM_String *name);</pre>
<param name="this"/>
<param name="name"/>
<desc>
Creates a <tt>DOM_Attr</tt> with the given <tt>name</tt> parameter. The <tt>DOM_Attr</tt> object may then be assigned to a <tt>DOM_Element</tt> using the <tt>DOM_Element_setAttributeNode</tt> function. All attributes of an element will be freed if the element is freed.
</desc>
<ret>The new <tt>DOM_Attr</tt> object or NULL of the operation failed in which case <tt>DOM_Exception</tt> will be set appropriately.</ret>
</meth>

<meth name="createEntityReference">
<pre>DOM_EntityReference *DOM_Document_createEntityReference(DOM_Document *this, DOM_String *name);</pre>
<param name="this"/>
<param name="name"/>
<desc>
Creates a <tt>DOM_EntityReference</tt> object.
<p/>
<i>Note: currently DOMC does not resolve entities, meaning the child list of a <tt>DOM_EntityReference</tt> will not be populated if the entity is known as it would in a full featured DOM implementation.</i>
</desc>
<ret>The new <tt>DOM_EntityReference</tt> object or NULL of the operation failed in which case <tt>DOM_Exception</tt> will be set appropriately.</ret>
</meth>

<meth name="getElementsByTagName">
<pre>DOM_NodeList *DOM_Document_getElementsByTagName(DOM_Document *this, DOM_String *tagname);</pre>
<param name="this"/>
<param name="tagname"/>
<desc>
The <tt>DOM_Document_getElementsByTagName</tt> function performs a preorder traversal of the entire document and returns a <tt>DOM_NodeList</tt> of the elements with the name <tt>tagname</tt> in the order in which they were encountered.
<p/>
After the <tt>DOM_NodeList</tt> object will no longer to be used it must be freed with the <tt>DOM_Document_destroyNodeList</tt> function with a <tt>free_nodes</tt> parameter of 0 (the nodes in this list should not be freed or all other references to them will be invalid).
</desc>
<ret>A new <tt>DOM_NodeList</tt> object containing pointers to the matching <tt>DOM_Element</tt>s.</ret>
</meth>
</group>

</interface>

