## BtPersistence

BtPersistence — object persistence interface

## Synopsis

    #include <libbtcore/core.h>

    struct              BtPersistenceInterface;
    void                bt_persistence_collect_hashtable_entries
                                                            (gpointer const key,
                                                             gpointer const value,
                                                             gpointer const user_data);
    gchar *             bt_persistence_get_value            (GValue * const gvalue);
    BtPersistence *     bt_persistence_load                 (const GType type,
                                                             const BtPersistence * const self,
                                                             xmlNodePtr node,
                                                             GError **err,
                                                             ...);
    gboolean            bt_persistence_load_hashtable       (GHashTable *hashtable,
                                                             xmlNodePtr node);
    gint                bt_persistence_parse_enum           (GType enum_type,
                                                             const gchar *str);
    xmlNodePtr          bt_persistence_save                 (const BtPersistence * const self,
                                                             xmlNodePtr const parent_node);
    gboolean            bt_persistence_save_hashtable       (GHashTable *hashtable,
                                                             xmlNodePtr const node);
    gboolean            bt_persistence_save_list            (const GList *list,
                                                             xmlNodePtr const node);
    gboolean            bt_persistence_set_value            (GValue * const gvalue,
                                                             const gchar * const svalue);
    const gchar *       bt_persistence_strfmt_double        (const gdouble val);
    const gchar *       bt_persistence_strfmt_enum          (GType enum_type,
                                                             gint value);
    const gchar *       bt_persistence_strfmt_long          (const glong val);
    const gchar *       bt_persistence_strfmt_uchar         (const guchar val);
    const gchar *       bt_persistence_strfmt_ulong         (const gulong val);

## Description

Classes can implement this interface to store their data as xml and restore them from xml. They should call the interface methods on their children objects (which also implement the interface) to serialize/ deserialize a whole object hierarchy.

## Details

### struct BtPersistenceInterface

    struct BtPersistenceInterface {
      /* virtual methods */
      xmlNodePtr (*save)(const BtPersistence * const self, xmlNodePtr const node);
      BtPersistence* (*load)(const GType type, const BtPersistence * const self, xmlNodePtr node, GError **err, va_list var_args);
    };

BtPersistence interface

`save` () | virtual method to serialize an object to an xml node
`load` () | virtual method to deserialze an object from an xml node

### bt_persistence_collect_hashtable_entries ()

    void                bt_persistence_collect_hashtable_entries
                                                            (gpointer const key,
                                                             gpointer const value,
                                                             gpointer const user_data);

Gather GHashTable entries in a list. Should be used with `g_hash_table_foreach()`.

`key` : | hashtable key
`value` : | hashtable value
`user_data` : | GList **list

### bt_persistence_get_value ()

    gchar *             bt_persistence_get_value            (GValue * const gvalue);

Returns the string representation of the given `gvalue`. Free it when done.

`gvalue` : | the event cell
Returns : | a newly allocated string with the data or `NULL` on error

### bt_persistence_load ()

    BtPersistence *     bt_persistence_load                 (const GType type,
                                                             const BtPersistence * const self,
                                                             xmlNodePtr node,
                                                             GError **err,
                                                             ...);

Deserializes the given object from the `node`. If `self` is NULL and a `type` is given it constructs a new object.

`type` : | a GObject type
`self` : | a deserialiable object
`node` : | the xml node
`err` : | a GError for deserialisation errors
`...` : | extra parameters NULL terminated name/value pairs.
Returns : | the deserialized object or `NULL`.

### bt_persistence_load_hashtable ()

    gboolean            bt_persistence_load_hashtable       (GHashTable *hashtable,
                                                             xmlNodePtr node);

Iterates over the xml-node and deserializes elements into the hashtable.

`hashtable` : | a GHashTable
`node` : | the list xml node
Returns : | `TRUE` if all elements have been deserialized.

### bt_persistence_parse_enum ()

    gint                bt_persistence_parse_enum           (GType enum_type,
                                                             const gchar *str);

Convinience methods, that parses a enum value nick and to get the corresponding intger value.

`enum_type` : | the GType for the enum
`str` : | the enum value name
Returns : | the interger value for the enum, or -1 for invalid strings.

### bt_persistence_save ()

    xmlNodePtr          bt_persistence_save                 (const BtPersistence * const self,
                                                             xmlNodePtr const parent_node);

Serializes the given object into `node`.

`self` : | a serialiable object
`parent_node` : | the parent xml node
Returns : | the new node if the object has been serialized, else `NULL`.

### bt_persistence_save_hashtable ()

    gboolean            bt_persistence_save_hashtable       (GHashTable *hashtable,
                                                             xmlNodePtr const node);

Iterates over a hashtable with strings and serializes them.

`hashtable` : | a GHashTable with strings
`node` : | the list xml node
Returns : | `TRUE` if all elements have been serialized.

### bt_persistence_save_list ()

    gboolean            bt_persistence_save_list            (const GList *list,
                                                             xmlNodePtr const node);

Iterates over a list of objects, which must implement the BtPersistence interface and calls `bt_persistence_save()` on each item.

`list` : | a GList `doc`; the xml-document
`node` : | the list xml node
Returns : | `TRUE` if all elements have been serialized.

### bt_persistence_set_value ()

    gboolean            bt_persistence_set_value            (GValue * const gvalue,
                                                             const gchar * const svalue);

Stores the supplied value into the given `gvalue`.

`gvalue` : | a GValue
`svalue` : | the string representation of the value to store
Returns : | `TRUE` for success

### bt_persistence_strfmt_double ()

    const gchar *       bt_persistence_strfmt_double        (const gdouble val);

Convinience methods, that formats a value to be serialized as a string.

`val` : | a value
Returns : | a reference to static memory containg the formatted value.

### bt_persistence_strfmt_enum ()

    const gchar *       bt_persistence_strfmt_enum          (GType enum_type,
                                                             gint value);

Convinience methods, that formats a value to be serialized as a string.

`enum_type` : | the GType for the enum
`value` : | the integer value for the enum
Returns : | a reference to static memory containg the formatted value.

### bt_persistence_strfmt_long ()

    const gchar *       bt_persistence_strfmt_long          (const glong val);

Convinience methods, that formats a value to be serialized as a string.

`val` : | a value
Returns : | a reference to static memory containg the formatted value.

### bt_persistence_strfmt_uchar ()

    const gchar *       bt_persistence_strfmt_uchar         (const guchar val);

Convinience methods, that formats a value to be serialized as a string.

`val` : | a value
Returns : | a reference to static memory containg the formatted value.

### bt_persistence_strfmt_ulong ()

    const gchar *       bt_persistence_strfmt_ulong         (const gulong val);

Convinience methods, that formats a value to be serialized as a string.

`val` : | a value
Returns : | a reference to static memory containg the formatted value.