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