DConfChangeset

## DConfChangeset DConfChangeset — A set of changes to a dconf database |

## Synopsis

                        DConfChangeset;
    gboolean            (*DConfChangesetPredicate)          (const gchar *path,
                                                             GVariant *value,
                                                             gpointer user_data);
    gboolean            dconf_changeset_all                 (DConfChangeset *changeset,
                                                             DConfChangesetPredicate predicate,
                                                             gpointer user_data);
    guint               dconf_changeset_describe            (DConfChangeset *changeset,
                                                             const gchar **prefix,
                                                             const gchar * const **paths,
                                                             GVariant * const **values);
    DConfChangeset *    dconf_changeset_deserialise         (GVariant *serialised);
    gboolean            dconf_changeset_get                 (DConfChangeset *changeset,
                                                             const gchar *key,
                                                             GVariant **value);
    gboolean            dconf_changeset_is_similar_to       (DConfChangeset *changeset,
                                                             DConfChangeset *other);
    DConfChangeset *    dconf_changeset_new                 (void);
    DConfChangeset *    dconf_changeset_new_write           (const gchar *path,
                                                             GVariant *value);
    DConfChangeset *    dconf_changeset_ref                 (DConfChangeset *changeset);
    GVariant *          dconf_changeset_serialise           (DConfChangeset *changeset);
    void                dconf_changeset_set                 (DConfChangeset *changeset,
                                                             const gchar *path,
                                                             GVariant *value);
    void                dconf_changeset_unref               (DConfChangeset *changeset);

## Description

DConfChangeset represents a set of changes that can be made to a dconf database. Currently supported operations are writing new values to keys and resetting keys and dirs.

Create the changeset with `dconf_changeset_new()` and populate it with `dconf_changeset_set()`. Submit it to dconf with `dconf_client_change_fast()` or `dconf_client_change_sync()`. `dconf_changeset_new_write()` is a convenience constructor for the common case of writing or resetting a single value.

## Details

### DConfChangeset

    typedef struct _DConfChangeset DConfChangeset;

This is a reference counted opaque structure type. It is not a GObject.

Use `dconf_changeset_ref()` and `dconf_changeset_unref()` to manipuate references.

### DConfChangesetPredicate ()

    gboolean            (*DConfChangesetPredicate)          (const gchar *path,
                                                             GVariant *value,
                                                             gpointer user_data);

Callback function type for predicates over items in a DConfChangeset.

Use with `dconf_changeset_all()`.

`path` : | a path, as per `dconf_is_path()`
`value` : | a GVariant, or `NULL`
`user_data` : | user data pointer
Returns : | `TRUE` if the predicate is met for the given `path` and `value`

### dconf_changeset_all ()

    gboolean            dconf_changeset_all                 (DConfChangeset *changeset,
                                                             DConfChangesetPredicate predicate,
                                                             gpointer user_data);

Checks if all changes in the changeset satisfy `predicate`.

`predicate` is called on each item in the changeset, in turn, until it returns `FALSE`.

If `preciate` returns `FALSE` for any item, this function returns `FALSE`. If not (including the case of no items) then this function returns `TRUE`.

`changeset` : | a DConfChangeset
`predicate` : | a DConfChangesetPredicate
`user_data` : | user data to pass to `predicate`
Returns : | `TRUE` if all items in `changeset` satisfy `predicate`

### dconf_changeset_describe ()

    guint               dconf_changeset_describe            (DConfChangeset *changeset,
                                                             const gchar **prefix,
                                                             const gchar * const **paths,
                                                             GVariant * const **values);

Describes `changeset`.

`prefix` and `paths` are presented in the same way as they are for the DConfClient::changed signal. `values` is an array of the same length as `paths`. For each key described by an element in `paths`, `values` will contain either a GVariant (the requested new value of that key) or `NULL` (to reset a reset).

The `paths` array is returned in an order such that dir will always come before keys contained within those dirs.

`changeset` : | a DConfChangeset
`prefix` : | the prefix under which changes have been requested
`paths` : | the list of paths changed, relative to `prefix`
`values` : | the list of values changed
Returns : | the number of changes (the length of `changes` and `values`).

### dconf_changeset_deserialise ()

    DConfChangeset *    dconf_changeset_deserialise         (GVariant *serialised);

Creates a DConfChangeset according to a serialised description returned from an earlier call to `dconf_changeset_serialise()`.

`serialised` has no particular format -- you should only pass a value that reasulted from an earlier serialise operation.

This call never fails, even if `serialised` is not in the correct format. Improperly-formatted parts are simply ignored.

`serialised` : | a GVariant from `dconf_changeset_serialise()`
Returns : | a new DConfChangeset

### dconf_changeset_get ()

    gboolean            dconf_changeset_get                 (DConfChangeset *changeset,
                                                             const gchar *key,
                                                             GVariant **value);

Checks if a DConfChangeset has an outstanding request to change the value of the given `key`.

If the change doesn't involve `key` then `FALSE` is returned and the `value` is unmodified.

If the change modifies `key` then `value` is set either to the value for that key, or `NULL` in the case that the key is being reset by the request.

`changeset` : | a DConfChangeset
`key` : | the key to check
`value` : | a return location for the value, or `NULL`
Returns : | `TRUE` if the key is being modified by the change

### dconf_changeset_is_similar_to ()

    gboolean            dconf_changeset_is_similar_to       (DConfChangeset *changeset,
                                                             DConfChangeset *other);

Checks if `changeset` is similar to `other`.

Two changes are considered similar if they write to the exact same set of keys. The values written are not considered.

This check is used to prevent building up a queue of repeated writes of the same keys. This is often seen when an application writes to a key on every move of a slider or an application window.

Strictly speaking, a write resettings all of "/a/" after a write containing "/a/b" could cause the later to be removed from the queue, but this situation is difficult to detect and is expected to be extremely rare.

`changeset` : | a DConfChangeset
`other` : | another DConfChangeset
Returns : | `TRUE` if the changes are similar

### dconf_changeset_new ()

    DConfChangeset *    dconf_changeset_new                 (void);

Creates a new, empty, DConfChangeset.

Returns : | the new DConfChangeset.

### dconf_changeset_new_write ()

    DConfChangeset *    dconf_changeset_new_write           (const gchar *path,
                                                             GVariant *value);

Creates a new DConfChangeset with one change. This is equivalent to calling `dconf_changeset_new()` and then `dconf_changeset_set()` with `path` and `value`.

`path` : | a dconf path
`value` : | a GVariant, or `NULL`
Returns : | a new DConfChangeset

### dconf_changeset_ref ()

    DConfChangeset *    dconf_changeset_ref                 (DConfChangeset *changeset);

Increases the reference count on `changeset`

`changeset` : | a DConfChangeset
Returns : | `changeset`

### dconf_changeset_serialise ()

    GVariant *          dconf_changeset_serialise           (DConfChangeset *changeset);

Serialises a DConfChangeset.

The returned value has no particular format and should only be passed to `dconf_changeset_deserialise()`.

`changeset` : | a DConfChangeset
Returns : | a floating GVariant

### dconf_changeset_set ()

    void                dconf_changeset_set                 (DConfChangeset *changeset,
                                                             const gchar *path,
                                                             GVariant *value);

Adds an operation to modify `path` to a DConfChangeset.

`path` may either be a key or a dir. If it is a key then `value` may be a GVariant, or `NULL` (to set or reset the key).

If `path` is a dir then this must be a reset operation: `value` must be `NULL`. It is not permitted to assign a GVariant value to a dir.

`changeset` : | a DConfChangeset
`path` : | a path to modify
`value` : | the value for the key, or `NULL` to reset

### dconf_changeset_unref ()

    void                dconf_changeset_unref               (DConfChangeset *changeset);

Releases a DConfChangeset reference.

`changeset` : | a DConfChangeset