EphyNodeDb

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"                 gchararray            : 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;

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

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

The "name" property

  "name"                 gchararray            : Read / Write / Construct Only

A string identifier unique to this EphyNodeDb

Default value: NULL