Xfconf Backend: xfconf Reference Manual

## Xfconf Backend Xfconf Backend — Interface for configuration store backends |

## Functions

gboolean | xfconf_backend_initialize ()
gboolean | xfconf_backend_is_property_locked ()
gboolean | xfconf_backend_list_channels ()
gboolean | xfconf_backend_set ()
gboolean | xfconf_backend_get ()
gboolean | xfconf_backend_get_all ()
gboolean | xfconf_backend_exists ()
gboolean | xfconf_backend_reset ()
gboolean | xfconf_backend_flush ()
void | xfconf_backend_register_property_changed_func ()
#define | xfconf_backend_return_val_if_fail()
void | (*XfconfPropertyChangedFunc) ()

## Types and Values

struct | XfconfBackendInterface
| XfconfBackend

## 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.

## Functions

### xfconf_backend_initialize ()

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

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

#### Parameters

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_is_property_locked ()

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

Queries whether or not the property on `channel` is locked by system policy.

#### Parameters

backend | The XfconfBackend. |
channel | A channel name. |
property | A property name. |
locked | 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_list_channels ()

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

Instructs the backend to return a list of channels with configuration data stored in the configuration store.

#### Parameters

backend | The XfconfBackend. |
channels | A pointer to a GSList head. |
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_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` .

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

backend | The XfconfBackend. |
func | A function of type XfconfPropertyChangedFunc. |
user_data | Arbitrary caller-supplied data. |

### xfconf_backend_return_val_if_fail()

    #define             xfconf_backend_return_val_if_fail(cond, val)

### XfconfPropertyChangedFunc ()

    void
    (*XfconfPropertyChangedFunc) (XfconfBackend *backend,
                                  const gchar *channel,
                                  const gchar *property,
                                  gpointer user_data);

## Types and Values

### 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.

#### Members

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.