API Notes

The popular C++ in c technique was not used. This means all methods are expressed as functions that follow the pattern:

DOM_Object_methodName(DOM_Object *obj, <parameters>)
where the first parameter is always the object the method is being invoked on. Simple typedefs are used to compensate for the lack of OO constructs in the c language. For example the following IDL samples from the W3C specification:

Element      createElement(in DOMString tagName raises(DOMException);
NodeList     getElementsByTagName(in DOMString name);
Node         appendChild(in Node newChild) raises(DOMException);
becomes:

DOM_Element *DOM_Document_createElement(DOM_Document *doc, const DOM_String *tagName);
DOM_NodeList *DOM_Element_getElementsByTagName(DOM_Element *element, const DOM_String *name);
DOM_Node *DOM_Node_appendChild(DOM_Node *node, DOM_Node *newChild);
I believe the only definitions in DOMC that are not specified in the W3C documentation are the DOM_Exception constants:

#define DOM_NO_MEMORY_ERR               11
#define DOM_NULL_POINTER_ERR            12
#define DOM_SYSTEM_ERR                  13
#define DOM_XML_PARSER_ERR              14
the memory management functions:

void DOM_Document_destroyNode(DOM_Document *doc, DOM_Node *node); 
void DOM_Document_destroyNodeList(DOM_Document *doc, DOM_NodeList *nl, int free_nodes);
void DOM_Document_destroyNamedNodeMap(DOM_Document *doc, DOM_NamedNodeMap *nnm, int free_nodes);
and load/save convenience operations (although these are modeled after the Load/Save Working Draft):

int DOM_DocumentLS_load(DOM_Document *doc, DOM_String *uri);
int DOM_DocumentLS_save(DOM_Document *doc, DOM_String *uri, DOM_Node *node);
Most functionality specified in Core Level 1, some from Level 2, and most of the DOM Event model has been implemented. However, some functionality with respect to EntityReferences, Notations, character encoding, and other peripherals are missing. This is not a religious implementation of the W3C recommendations (yet). Regardless, the package should be immediately useable for many contexts although HTML is not supported and I have no plans to support it in the future.

Below is an example program (something I always look for when evaluating a new package) that was used to test DOMC. There are several more example programs packaged with the distribution.


/* d4.c
 *
 * Load the XML file specified on the command line and build a DOM tree
 * returned as a DOM_Document object. Get the root (yes, that union is a
 * little strange -- doesn't happen a lot) and add some new elements using
 * a DOM_DocumentFragment object. Then save the result as XML to stdout.
 */

#include <stdlib.h>
#include <stdio.h>
#include "dom.h"

int
main(int argc, char *argv[])
{
    DOM_Document *doc;
    DOM_DocumentFragment *dfrag;
    DOM_Element *root, *e0, *e1;
    DOM_Text *t0;

    if (argc < 2) {
        return EXIT_FAILURE;
    }

    doc = DOM_Implementation_createDocument(NULL, NULL, NULL);
    if (DOM_DocumentLS_load(doc, argv[1]) == 0) {
        return EXIT_FAILURE;
    }

    root = doc->u.Document.documentElement;

    dfrag = DOM_Document_createDocumentFragment(doc);
    e0 = DOM_Document_createElement(doc, "foo");
    e1 = DOM_Document_createElement(doc, "bar");
    t0 = DOM_Document_createTextNode(doc, "This tests the DocumentFragment \
            operations such as properly moving nodes from the \
            DocumentFragment into the children of another.");

    DOM_Node_appendChild(dfrag, e0);
    DOM_Node_appendChild(dfrag, e1);
    DOM_Node_appendChild(dfrag, t0);

    if (DOM_Node_appendChild(root->lastChild, dfrag) == NULL) {
		return EXIT_FAILURE;
    }

    if (DOM_DocumentLS_save(doc, "/dev/stdout", NULL) == 0) {
        return EXIT_FAILURE;
    }

    DOM_Document_destroyNode(doc, dfrag);
    DOM_Document_destroyNode(doc, doc);

    return EXIT_SUCCESS;
}