domnode(3m)

NAME
domnode - a dom-like api for manipulating xml as a tree of nodes

SYNOPSIS
#include <mba/domnode.h>

struct domnode {
const char *name;
const char *value;
struct linkedlist *children;
struct linkedlist *attrs;
};

struct domnode *domnode_new(const char *name, const char *value);
void domnode_del(void *this);

int domnode_load(struct domnode *this, const char *filename);
int domnode_store(struct domnode *this, const char *filename);
size_t domnode_read(struct domnode *this, FILE *stream);
size_t domnode_write(struct domnode *this, FILE *stream);
struct domnode *domnode_search(struct domnode *this, const char *name);

int domnode_attrs_put(struct linkedlist *attrs, struct domnode *attr);
struct domnode *domnode_attrs_get(struct linkedlist *attrs, const char *name);
struct domnode *domnode_attrs_remove(struct linkedlist *attrs, const char *name);

DESCRIPTION
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.

new The domnode_new function creates a new domnode structure with the specified name and value. 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. Otherwise, consult Tablefor appropriate name and value parameters. If both name and value are null pointers an "empty" node is created suitable for creating a new domnode tree from an XML source file with the domnode_load or domnode_read functions.

del The domnode_del function recursively releases the resources associated with this domnode structure and its children and attributes. If this node is a null pointer, no action is taken. Any additional memory management performed by the user should consider that the name and value members of this node and all of its attributes, children, and children's attributes will also be deallocated with the free(3) function.

load
    The domnode_load function loads an XML source file from the file specified by the filename parameter and populates the element node this with the corresponding domnode tree. Any existing members of this element will be deallocated. The XML source file must be a complete well-formed XML document. The possible XML source file character encodings are UTF-8, UTF-16, ISO-8859-1, or US-ASCII.

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

    cfg = domnode_new(NULL, NULL);
    if (domnode_load(cfg, argv[1]) == 0) {
        fprintf(stderr, "Failed to load XML configuration file: %s", argv[1]);
        return 0;
    }

store
    The domnode_store function serializes this domnode tree 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).

read
    The domnode_read function reads an XML source file from stream and populates the element node this with the corresponding domnode tree. Any existing members of this element will be deallocated. The XML source file must be a complete well-formed XML document. The possible XML source file character encodings are UTF-8, UTF-16, ISO-8859-1, or US-ASCII.

write
    The domnode_write function serializes this domnode tree as XML source and writes the output to stream using the locale dependent character encoding (e.g. UTF-8).

search
    The domnode_search function performs a breadth-first-search on the entire tree for a named element or attribute node starting from this 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.

attrs_put
    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) == 0) {
        domnode_del(attr);
        return 0;
    }

attrs_get
    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.

attrs_remove
    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.

RETURNS

new The domnode_new function returns a new domnode structure. If memory for the structure cannot be allocated a null pointer is returned and errno is set to ENOMEM. Domnode structures should be freed with the domnode_del function.

del The domnode_del function returns no value.

load
    The domnode_load function returns non-zero if the operation was successfull. Otherwise, zero is returned and errno is set to indicate that the operation failed.

store
    The domnode_store function returns non-zero if the operation was successfull. Otherwise, zero is returned and errno is set to indicate that the operation failed.

read
    The domnode_read 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.

write
    The domnode_write 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.

search
    The domnode_search function returns the matching element or attribute or a null pointer if no such node exists in the tree.

attrs_put
    The domnode_attrs_put function returns non-zero if the operation was successfull. Otherwise, zero is returned and errno is set to indicate that the operation failed.

attrs_get
    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.

attrs_remove
    The domnode_attrs_remove function returns the attribute node removed. If the named attibute is not found a null pointer is returned.