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

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

A string identifier unique to this EphyNodeDb

Default value: NULL

Generated by GTK-Doc V1.10