DConfChangeset: dconf Reference Manual

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

## Functions

gboolean | (*DConfChangesetPredicate) ()
gboolean | dconf_changeset_all ()
void | dconf_changeset_change ()
guint | dconf_changeset_describe ()
DConfChangeset * | dconf_changeset_deserialise ()
DConfChangeset * | dconf_changeset_diff ()
gboolean | dconf_changeset_get ()
gboolean | dconf_changeset_is_empty ()
gboolean | dconf_changeset_is_similar_to ()
DConfChangeset * | dconf_changeset_new ()
DConfChangeset * | dconf_changeset_new_database ()
DConfChangeset * | dconf_changeset_new_write ()
DConfChangeset * | dconf_changeset_ref ()
GVariant * | dconf_changeset_serialise ()
void | dconf_changeset_set ()
void | dconf_changeset_unref ()
void | dconf_changeset_seal ()

## Types and Values

| DConfChangeset

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

## Functions

### 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()`.

#### Parameters

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 `predicate` returns `FALSE` for any item, this function returns `FALSE`. If not (including the case of no items) then this function returns `TRUE`.

#### Parameters

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

    void
    dconf_changeset_change (DConfChangeset *changeset,
                            DConfChangeset *changes);

Applies `changes` to `changeset` .

If `changeset` is a normal changeset then reset requests in `changes` will be allied to `changeset` and then copied down into it. In this case the two changesets are effectively being merged.

If `changeset` is in database mode then the reset operations in `changes` will simply be applied to `changeset` .

#### Parameters

changeset | a DConfChangeset (to be changed) |
changes | the changes to make to `changeset` |

Since: 0.16

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

If `changeset` is not already sealed then this call will implicitly seal it. See `dconf_changeset_seal()`.

#### Parameters

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 resulted from an earlier serialise operation.

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

#### Parameters

serialised | a GVariant from `dconf_changeset_serialise()` |

#### Returns

a new DConfChangeset

### dconf_changeset_diff ()

    DConfChangeset *
    dconf_changeset_diff (DConfChangeset *from,
                          DConfChangeset *to);

Compares to database-mode changesets and produces a changeset that describes their differences.

If there is no difference, `NULL` is returned.

Applying the returned changeset to `from` using `dconf_changeset_change()` will result in the two changesets being equal.

#### Parameters

from | a database mode changeset |
to | a database mode changeset |

#### Returns

the changes, or `NULL`.

[transfer full]

Since: 0.16

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

#### Parameters

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

    gboolean
    dconf_changeset_is_empty (DConfChangeset *changeset);

Checks if `changeset` is empty (ie: contains no changes).

#### Parameters

changeset | a DConfChangeset |

#### Returns

`TRUE` if `changeset` is empty

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

#### Parameters

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

    DConfChangeset *
    dconf_changeset_new_database (DConfChangeset *copy_of);

Creates a new DConfChangeset in "database" mode, possibly initialising it with the values of another changeset.

In a certain sense it's possible to imagine that a DConfChangeset could express the contents of an entire dconf database -- the contents are the database are what you would have if you applied the changeset to an empty database. One thing that fails to map in this analogy are reset operations -- if we start with an empty database then reset operations are meaningless.

A "database" mode changeset is therefore a changeset which is incapable of containing reset operations.

It is not permitted to use a database-mode changeset for most operations (such as the `change` argument to `dconf_changeset_change()` or the `changeset` argument to DConfClient APIs).

If `copy_of` is non-`NULL` then its contents will be copied into the created changeset. `copy_of` must be a database-mode changeset.

#### Parameters

copy_of | a DConfChangeset to copy. | [allow-none]

#### Returns

a new DConfChangeset in "database" mode

Since: 0.16

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

#### Parameters

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`

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

changeset | a DConfChangeset |

### dconf_changeset_seal ()

    void
    dconf_changeset_seal (DConfChangeset *changeset);

Seals `changeset` .

When a DConfChangeset is first created, it is mutable and non-threadsafe. Once the changeset is populated with the required changes, it can be shared between multiple threads, but only by making it immutable by "sealing" it.

After the changeset is sealed, you cannot call `dconf_changeset_set()` or any other functions that would modify it. It is safe, however, to share it between multiple threads.

All changesets are unsealed on creation, including those that are made by copying changesets that are sealed. `dconf_changeset_describe()` will implicitly seal a changeset.

This function is idempotent.

#### Parameters

changeset | a DConfChangeset |

Since: 0.18

## Types and Values

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