XfconfBackend
3
XFCONF Library

# XfconfBackend

Interface for configuration store backends

## Synopsis

                        XfconfBackendInterface;
                        XfconfBackend;
    gboolean            xfconf_backend_initialize           (XfconfBackend *backend,
                                                             GError **error);
    gboolean            xfconf_backend_set                  (XfconfBackend *backend,
                                                             const gchar *channel,
                                                             const gchar *property,
                                                             const GValue *value,
                                                             GError **error);
    gboolean            xfconf_backend_get                  (XfconfBackend *backend,
                                                             const gchar *channel,
                                                             const gchar *property,
                                                             GValue *value,
                                                             GError **error);
    gboolean            xfconf_backend_get_all              (XfconfBackend *backend,
                                                             const gchar *channel,
                                                             const gchar *property_base,
                                                             GHashTable *properties,
                                                             GError **error);
    gboolean            xfconf_backend_exists               (XfconfBackend *backend,
                                                             const gchar *channel,
                                                             const gchar *property,
                                                             gboolean *exists,
                                                             GError **error);
    gboolean            xfconf_backend_reset                (XfconfBackend *backend,
                                                             const gchar *channel,
                                                             const gchar *property,
                                                             gboolean recursive,
                                                             GError **error);
    gboolean            xfconf_backend_flush                (XfconfBackend *backend,
                                                             GError **error);
    void                xfconf_backend_register_property_changed_func
                                                            (XfconfBackend *backend,
                                                             XfconfPropertyChangedFunc func,
                                                             gpointer user_data);

## Object Hierarchy

      GInterface
       +----XfconfBackend

## Prerequisites

XfconfBackend requires GObject.

## Description

XfconfBackend is an abstract interface that allows the Xfconf Daemon to use different backends for storing configuration data. These backends can be flat text or binary files, a database, or just about anything one could think of to store data.

## Details

### XfconfBackendInterface

    typedef struct {
        GTypeInterface parent;

        gboolean (*initialize)(XfconfBackend *backend,
                               GError **error);

        gboolean (*set)(XfconfBackend *backend,
                        const gchar *channel,
                        const gchar *property,
                        const GValue *value,
                        GError **error);

        gboolean (*get)(XfconfBackend *backend,
                        const gchar *channel,
                        const gchar *property,
                        GValue *value,
                        GError **error);

        gboolean (*get_all)(XfconfBackend *backend,
                            const gchar *channel,
                            const gchar *property_base,
                            GHashTable *properties,
                            GError **error);

        gboolean (*exists)(XfconfBackend *backend,
                           const gchar *channel,
                           const gchar *property,
                           gboolean *exists,
                           GError **error);

        gboolean (*reset)(XfconfBackend *backend,
                          const gchar *channel,
                          const gchar *property,
                          gboolean recursive,
                          GError **error);

        gboolean (*list_channels)(XfconfBackend *backend,
                                  GSList **channels,
                                  GError **error);

        gboolean (*is_property_locked)(XfconfBackend *backend,
                                       const gchar *channel,
                                       const gchar *property,
                                       gboolean *locked,
                                       GError **error);

        gboolean (*flush)(XfconfBackend *backend,
                          GError **error);

        void (*register_property_changed_func)(XfconfBackend *backend,
                                               XfconfPropertyChangedFunc func,
                                               gpointer user_data);

        /*< reserved for future expansion >*/
        void (*_xb_reserved0)();
        void (*_xb_reserved1)();
        void (*_xb_reserved2)();
        void (*_xb_reserved3)();
    } XfconfBackendInterface;

An interface for implementing pluggable configuration store backends into the Xfconf Daemon.

See the XfconfBackend function documentation for a description of what each virtual function in XfconfBackendInterface should do.

GTypeInterface parent;

  GObject interface parent.

initialize ()

  See `xfconf_backend_initialize()`.

set ()

  See `xfconf_backend_set()`.

get ()

  See `xfconf_backend_get()`.

get_all ()

  See `xfconf_backend_get_all()`.

exists ()

  See `xfconf_backend_exists()`.

reset ()

  See `xfconf_backend_reset()`.

list_channels ()

  See `xfconf_backend_list_channels()`.

is_property_locked ()

  See `xfconf_backend_is_property_locked()`.

flush ()

  See `xfconf_backend_flush()`.

register_property_changed_func ()

  See `xfconf_backend_register_property_changed_func()`.

_xb_reserved0 ()

  Reserved for future expansion.

_xb_reserved1 ()

  Reserved for future expansion.

_xb_reserved2 ()

  Reserved for future expansion.

_xb_reserved3 ()

  Reserved for future expansion.

### XfconfBackend

    typedef struct _XfconfBackend XfconfBackend;

An instance of a class implementing a XfconfBackendInterface.

### xfconf_backend_initialize ()

    gboolean            xfconf_backend_initialize           (XfconfBackend *backend,
                                                             GError **error);

Does any pre-initialization that the backend needs to function.

`backend` :

  The XfconfBackend.

`error` :

  An error return.

Returns :

  The backend should return `TRUE` if initialization was successful, or `FALSE` otherwise. On `FALSE`, `error` should be set to a description of the failure.

### xfconf_backend_set ()

    gboolean            xfconf_backend_set                  (XfconfBackend *backend,
                                                             const gchar *channel,
                                                             const gchar *property,
                                                             const GValue *value,
                                                             GError **error);

Sets the variant `value` for `property` on `channel`.

`backend` :

  The XfconfBackend.

`channel` :

  A channel name.

`property` :

  A property name.

`value` :

  A value.

`error` :

  An error return.

Returns :

  The backend should return `TRUE` if the operation was successful, or `FALSE` otherwise. On `FALSE`, `error` should be set to a description of the failure.

### xfconf_backend_get ()

    gboolean            xfconf_backend_get                  (XfconfBackend *backend,
                                                             const gchar *channel,
                                                             const gchar *property,
                                                             GValue *value,
                                                             GError **error);

Gets the value of `property` on `channel` and stores it in `value`.

`backend` :

  The XfconfBackend.

`channel` :

  A channel name.

`property` :

  A property name.

`value` :

  A GValue return.

`error` :

  An error return.

Returns :

  The backend should return `TRUE` if the operation was successful, or `FALSE` otherwise. On `FALSE`, `error` should be set to a description of the failure.

### xfconf_backend_get_all ()

    gboolean            xfconf_backend_get_all              (XfconfBackend *backend,
                                                             const gchar *channel,
                                                             const gchar *property_base,
                                                             GHashTable *properties,
                                                             GError **error);

Gets multiple properties and values on `channel` and stores them in `properties`, which is already initialized to hold gchar* keys and GValue* values. The `property_base` parameter can be used to limit the retrieval to a sub-tree of the property tree.

A value of the empty string ("") or forward slash ("/") for `property_base` indicates the entire channel.

`backend` :

  The XfconfBackend.

`channel` :

  A channel name.

`property_base` :

  The base of properties to return.

`properties` :

  A GHashTable.

`error` :

  An error return.

Returns :

  The backend should return `TRUE` if the operation was successful, or `FALSE` otherwise. On `FALSE`, `error` should be set to a description of the failure.

### xfconf_backend_exists ()

    gboolean            xfconf_backend_exists               (XfconfBackend *backend,
                                                             const gchar *channel,
                                                             const gchar *property,
                                                             gboolean *exists,
                                                             GError **error);

Checks to see if `property` exists on `channel`, and stores `TRUE` or `FALSE` in `exists`.

`backend` :

  The XfconfBackend.

`channel` :

  A channel name.

`property` :

  A property name.

`exists` :

  A boolean return.

`error` :

  An error return.

Returns :

  The backend should return `TRUE` if the operation was successful, or `FALSE` otherwise. On `FALSE`, `error` should be set to a description of the failure.

### xfconf_backend_reset ()

    gboolean            xfconf_backend_reset                (XfconfBackend *backend,
                                                             const gchar *channel,
                                                             const gchar *property,
                                                             gboolean recursive,
                                                             GError **error);

Resets the property identified by `property` from `channel`. If `recursive` is `TRUE`, all sub-properties of `property` will be reset as well. If the empty string ("") or a forward slash ("/") is specified for `property`, the entire channel will be reset.

If none of the properties specified are locked or have root-owned system-wide defaults set, this effectively removes the properties from the configuration store entirely.

`backend` :

  The XfconfBackend.

`channel` :

  A channel name.

`property` :

  A property name.

`recursive` :

  Whether or not the reset is recursive.

`error` :

  An error return.

Returns :

  The backend should return `TRUE` if the operation was successful, or `FALSE` otherwise. On `FALSE`, `error` should be set to a description of the failure.

### xfconf_backend_flush ()

    gboolean            xfconf_backend_flush                (XfconfBackend *backend,
                                                             GError **error);

For backends that support persistent storage, ensures that all configuration data stored in memory is saved to persistent storage.

`backend` :

  The XfconfBackend.

`error` :

  An error return.

Returns :

  The backend should return `TRUE` if the operation was successful, or `FALSE` otherwise. On `FALSE`, `error` should be set to a description of the failure.

### xfconf_backend_register_property_changed_func ()

    void                xfconf_backend_register_property_changed_func
                                                            (XfconfBackend *backend,
                                                             XfconfPropertyChangedFunc func,
                                                             gpointer user_data);

Registers a function to be called when a property changes. The backend implementation should keep a pointer to `func` and `user_data` and call `func` when a property in the configuration store changes.

`backend` :

  The XfconfBackend.

`func` :

  A function of type XfconfPropertyChangeFunc.

`user_data` :

  Arbitrary caller-supplied data.