GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  DOM_DOCUMENT (3)

NAME

DOM_Document - the Document Object Model (DOM) DOM_Document interface

CONTENTS

Synopsis
Description
Returns

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.
Search for    or go to Top of page |  Section 3 |  Main Index


domc-0.8.0 DOM_DOCUMENT (3m) Sep 9, 2004

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.