## EphyNodeDb EphyNodeDb — Data tree |

## Synopsis

                EphyNodeDb;
    EphyNodeDb* ephy_node_db_get_by_name        (const char *name);
    EphyNodeDb* ephy_node_db_new                (const char *name);
    gboolean    ephy_node_db_load_from_file     (EphyNodeDb *db,
                                                 const char *xml_file,
                                                 const xmlChar *xml_root,
                                                 const xmlChar *xml_version);
    int         ephy_node_db_write_to_xml_safe  (EphyNodeDb *db,
                                                 const xmlChar *filename,
                                                 const xmlChar *root,
                                                 const xmlChar *version,
                                                 const xmlChar *comment,
                                                 EphyNode *node,
                                                 ...);
    const char* ephy_node_db_get_name           (EphyNodeDb *db);
    gboolean    ephy_node_db_is_immutable       (EphyNodeDb *db);
    void        ephy_node_db_set_immutable      (EphyNodeDb *db,
                                                 gboolean immutable);
    EphyNode*   ephy_node_db_get_node_from_id   (EphyNodeDb *db,
                                                 guint id);

## Object Hierarchy

      GObject
       +----EphyNodeDb

## Properties

      "immutable"            gboolean              : Read / Write
      "name"                 gchararray            : Read / Write

## Description

An EphyNodeDb is a database for arbitrary data organized in a tree.

Each database is stored along with its name in a global set of databases. Databases can be created using `ephy_node_db_new()` and retrieved using `ephy_node_db_get_by_name()`.

Each EphyNode inside an EphyNodeDb is identified by a unique node ID. By keeping a handle on the ID, one can use `ephy_node_db_get_node_from_id()` to retrieve its corresponding EphyNode.

EphyNodeDbs can be saved to disk using `ephy_node_db_write_to_xml_safe()` and restored using `ephy_node_db_load_from_file()`.

## Details

### EphyNodeDb

    typedef struct _EphyNodeDb EphyNodeDb;

### ephy_node_db_get_by_name ()

    EphyNodeDb* ephy_node_db_get_by_name        (const char *name);

Returns the EphyNodeDb named `name`, or `NULL` if no such database exists.

`name` : | the name of the desired EphyNodeDb
Returns : | an EphyNodeDb

### ephy_node_db_new ()

    EphyNodeDb* ephy_node_db_new                (const char *name);

Creates and returns a new EphyNodeDb, named `name`.

`name` : | the name of the new EphyNodeDb
Returns : | the new EphyNodeDb

### ephy_node_db_load_from_file ()

    gboolean    ephy_node_db_load_from_file     (EphyNodeDb *db,
                                                 const char *xml_file,
                                                 const xmlChar *xml_root,
                                                 const xmlChar *xml_version);

Populates `db` with data from `xml_file`. The node database will be populated with everything inside of the `xml_root` tag from `xml_file`. If `xml_version` is different from the version attribute of the `xml_root` element, this function will fail.

The data will most probably have been stored using `ephy_node_db_write_to_xml_safe()`.

`db` : | a new EphyNodeDb
`xml_file` : | the filename from which `db` will be populated
`xml_root` : | the root element in `xml_file`
`xml_version` : | the required version attribute in the `xml_root`
Returns : | `TRUE` if successful

### ephy_node_db_write_to_xml_safe ()

    int         ephy_node_db_write_to_xml_safe  (EphyNodeDb *db,
                                                 const xmlChar *filename,
                                                 const xmlChar *root,
                                                 const xmlChar *version,
                                                 const xmlChar *comment,
                                                 EphyNode *node,
                                                 ...);

Writes `db`'s data to an XML file for storage. The data can be retrieved in the future using `ephy_node_db_load_from_file()`.

The function arguments are straightforward until `node`, at which point some explanation is necessary.

The variable argument list starts at `node`, which is an EphyNode containing data to write to `filename`. The next argument is an integer specifying the number of “exception” nodes. After this integer, that number of EphyNode arguments should be given. Each of these “exception” nodes determines which data out of `node` will not be written to `filename`.

To insert all of an EphyNode's contents without exception, simply give the integer `0` after `node`.

The remainder of this function's arguments will be groups of such EphyNode - integer - (list of EphyNodes). Finally, the last argument must be `NULL`.

`db` : | an EphyNodeDb
`filename` : | the XML file in which `db`'s data will be stored
`root` : | the desired root element in `filename`
`version` : | the version attribute to the `root` element
`comment` : | a comment to place directly inside the `root` element of `filename`
`node` : | The first node of data to write
`...` : | number of exceptions, list of their EphyNodes, and more such sequences, followed by `NULL`
Returns : | `0` on success or a negative number on failure

### ephy_node_db_get_name ()

    const char* ephy_node_db_get_name           (EphyNodeDb *db);

`db` : | an EphyNodeDb
Returns : | the name of `db`

### ephy_node_db_is_immutable ()

    gboolean    ephy_node_db_is_immutable       (EphyNodeDb *db);

`db` : | an EphyNodeDb
Returns : | `TRUE` if `db` is immutable

### ephy_node_db_set_immutable ()

    void        ephy_node_db_set_immutable      (EphyNodeDb *db,
                                                 gboolean immutable);

If `immutable` is `TRUE`, sets `db` immutable (read-only). Otherwise, sets `db` to be read-write.

`db` : | an EphyNodeDb
`immutable` : | `TRUE` to make `db` immutable

### ephy_node_db_get_node_from_id ()

    EphyNode*   ephy_node_db_get_node_from_id   (EphyNodeDb *db,
                                                 guint id);

Returns the EphyNode with id `id` from `db`, or `NULL` if no such id exists.

`db` : | an EphyNodeDb
`id` : | an id specifying an EphyNode in `db`
Returns : | an EphyNode

## Properties

### The "`immutable`" property

      "immutable"            gboolean              : Read / Write

`TRUE` if no EphyNodes can be added, removed or modified from this EphyNodeDb

Default value: FALSE

### The "`name`" property

      "name"                 gchararray            : Read / Write

A string identifier unique to this EphyNodeDb

Default value: NULL