Copyright 2002 Michael B. Allen <mba2000 ioplex.com> mba/domnode.h Domnode The domnode(3m) module provides a lightweight DOM-like interface for manipulating XML documents as a tree of nodes in memory. Functions are provided to load and store XML sources to and from trees of domnode structures. It follows the "everything is a node philosophy". Four different node types are supported; element, attribute, text, and comment. The linkedlist(3m) functions are used to modify the children and attributes of a node. All locale dependant character encodings as well as wide character encodings are supported with the tchar abstraction. The Expat XML parser is used by default which supports UTF-8, UTF-16, ISO-8859-1, or US-ASCII. This module will generate XML files in the locale dependant encoding. An XML configuration file Consider the following XML fragment from an imaginary networking application. The root node in this example is zsvr. It has children #comment, net, and users. The net element has attributes laddr, timeout, and port. See the domnode_create function for a complete description of the four different node types. 
<zsvr mode="server">
    <!-- This is a comment -->
    <net laddr="192.168.1.15" timeout="15000" port="1444"/>
    <users>
        This is some text
        <user id="mba" auth="nis.o">nis.foo.net:9812:fretos</user>
        <user id="gchan"
The values of these configuration parameters should be manipulated by iterating over elements and attributes with linkedlist_iterate and linkedlist_next and then getting or setting individual values through the value member of the domnode structure.

Please be aware that the space between elements is included in the list of children as #text nodes. This is consistent with a real DOM and is necessary if indentation and spacing in the original document is to be preserved. If your program is not interested in this space then be prepared to ignore those #text nodes.

As a convienience there is also a search function to retrieve a particular element or attribute provided it's name is unique among all elements and attributes. The following code sets the port value of a sockaddr_in structure to the port value "1444". 

if ((attr = domnode_search(cfg, "port")) != NULL) {
    inet.sin_port = htons(atoi(attr->value));
}
The <ident>domnode</ident> structure The <ident>domnode</ident> structure 
#include <mba/linkedlist.h>

struct domnode {
	const tchar *name;
	const tchar *value; 
	struct linkedlist *children;
	struct linkedlist *attrs; 
};
Values of <ident>struct domnode</ident> members by node type
Type Members
  name value children attrs
Element tag name NULL linkedlist linkedlist
Attribute name of the attribute value of the attribute NULL NULL
Text "#text" content of text node NULL NULL
Comment "#comment" content of comment NULL NULL
The domnode structure represents one of four possible node types; element, attribute, text, or comment. Table shows what the domnode structure members may be for each node type. This table should be considered when creating new nodes with the domnode_new function.
Memory management functions These functions should be used to create and destroy domnode objects. 
int domnode_create(struct domnode *dn, const tchar *name, const tchar *value, struct allocator *al);
The domnode_create function initializes the domnode object dn with the specified name and value. The allocator al will be used to allocate memory for this object. The domnode_destroy function must be called to free all memory associated with this object and it's children back to the allocator al.

The type of the node created depends on the parameters specified. If the name parameter is the string '#text' a text node is created. If the name parameter is the string '#comment' a comment node is created. If the value parameter is NULL an element is created. If both name and value are NULL an "empty" node is created suitable for creating a new domnode tree from an XML source file with the functions domnode_load or domnode_fread. The domnode_create function returns 0 if the domnode was created successfully or -1 if the operation failed in which case errno will be set appropriately. 

int domnode_destroy(struct domnode *dn);
The domnode_destroy function recursively releases resources associated with the domnode object dn as well as its children and attributes. The domnode_destroy function returns 0 if the domnode and it's children were successfully destroyed or -1 if the operation failed in which case errno will be set appropriately. If the dn parameter is NULL, no action is taken. 
struct domnode *domnode_new(const tchar *name, const tchar *value, struct allocator *al);
The domnode_new function allocates memory for a new domnode object an initializes it with the domnode_create function. 
void domnode_del(void *dn);
The domnode_del function destroys the object dn with the domnode_destroy function and then frees dn itself. Node functions 
int domnode_load(struct domnode *dn, const char *filename);
The domnode_load function loads an XML source file from the file specified by the filename parameter and populates the node dn with the corresponding domnode tree. Any existing members of the dn object will be deallocated. The XML source file must be a complete well-formed XML document.

The following code illustrates how to create an initially empty root node and load an XML source document into it. 

dn = domnode_new(NULL, NULL, NULL);
if (dn == NULL || domnode_load(dn, argv[1]) == 0) { 
    fprintf(stderr, "Failed to load XML file: %s", argv[1]);
    return 0;
}
The domnode_load function returns 0 if the operation was successful. Otherwise, -1 is returned and errno is set to indicate that the operation failed. 
int domnode_store(struct domnode *dn, const char *filename);
The domnode_store function serializes the domnode tree identified by dn as XML source and writes the output to the file specified by the filename parameter using the locale dependent character encoding (e.g. UTF-8). The domnode_store function returns 0 if the operation was successful. Otherwise, -1 is returned and errno is set to indicate that the operation failed. 
size_t domnode_fread(struct domnode *dn, FILE *stream);
The domnode_fread function reads an XML source file from stream and populates the element node dn with the corresponding domnode tree. Any existing members of the dn object will be deallocated. The XML source file must be a complete well-formed XML document. The domnode_fread function returns the number of bytes read from stream or (size_t)(-1) if the operation failed in which case errno will be set appropriately. 
size_t domnode_fwrite(struct domnode *dn, FILE *stream);
The domnode_fwrite function serializes dn domnode tree as XML source and writes the output to stream using the locale dependent character encoding (e.g. UTF-8). The domnode_fwrite function returns the number of bytes written to stream or (size_t)(-1) if the operation failed in which case errno will be set appropriately. 
struct domnode *domnode_search(struct domnode *dn, const tchar *name);
The domnode_search function performs a breadth-first-search on the entire tree for a named element or attribute node starting from dn node. The first node with a name matching the name parameter is returned. If no such node is found, a null pointer is returned.

In general this function should not be used because it is common for the name of an element or attribute to be repeated several times throughout the tree in which case the user cannot always be certain which node will be found. The domnode_search function returns the matching element or attribute or a null pointer if no such node exists in the tree. Attribute functions The domnode attribute functions provide a map interface for manipulating attributes of an element. 

int domnode_attrs_put(struct linkedlist *attrs, struct domnode *attr);
The domnode_attrs_put function puts an attribute into a list of attributes of an element. The attrs parameter is the attrs member of the target element. The attr parameter is the attribute that should be placed into this list of attributes. If an attribute with the same name already exists in the list, it will be freed and then replaced with the new attribute. The below code illustrates how to create a new attribute and add it to the attributes of the net element from Example 
if ((attr = domnode_new("baddr", "192.168.1.255")) == NULL ||
            domnode_attr_put(net->attrs, attr) == -1) {
    domnode_del(attr);
    return -1;
}
The domnode_attrs_put function returns 0 if the operation was successful. Otherwise, -1 is returned and errno is set to indicate that the operation failed. 
struct domnode *domnode_attrs_get(struct linkedlist *attrs, const tchar *name);
The domnode_attrs_get function retrieves an attribute from the attributes of an element by it's name. The attrs parameter is the attrs member of the target element. The name parameter is the name of the attribute that should be retrieved from the list of attributes. The domnode_attrs_get function returns the attribute that is being retrieved. If no attribute with the specified name exists in the attrs list, a null pointer is returned. 
struct domnode *domnode_attrs_remove(struct linkedlist *attrs, const tchar *name);
The domnode_attrs_remove function removes an attribute from the attibutes of an element by it's name. The attrs parameter is the attrs member of the target element. The name parameter is the name of the attribute that should be removed from the list of attributes. The domnode_attrs_remove function returns the attribute node removed. If the named attibute is not found a null pointer is returned.