EphyNodeDb 3 EPIPHANY Library
EphyNodeDb Data tree

## Synopsis

                        EphyNodeDb;
    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"                     gchar*                : Read / Write / Construct Only

## 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;

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_new

### 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_load_from_file

### 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_write_to_xml_safe

### 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_get_name

### 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_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_set_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

ephy_node_db_get_node_from_id

## Property Details

### The `"immutable"` property

      "immutable"                gboolean              : Read / Write

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

Default value: FALSE

EphyNodeDb:immutable

### The `"name"` property

      "name"                     gchar*                : Read / Write / Construct Only

A string identifier unique to this EphyNodeDb

Default value: NULL

EphyNodeDb:name