XfconfBackend

## XfconfBackend XfconfBackend — Interface for configuration store backends |

## Synopsis

    struct              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

### struct XfconfBackendInterface

    struct XfconfBackendInterface {
        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)();
    };

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.