MateConfChangeSet

MateConfChangeSet — a set of configuration changes to be made.

Functions

Types and Values

Description

a MateConfChangeSet allows you to collect a set of changes to configuration keys (set/unset operations). You can then commit all the changes at once. This is convenient for something like a preferences dialog; you can collect all the pending changes in a MateConfChangeSet, then when the user clicks "apply" send them all to the configuration database. The MateConfChangeSet allows you to avoid sending every preferences setting when "apply" is clicked; you only have to send the settings the user changed.

In the future, MateConf may also have optimizations so that changing a group of values with MateConfChangeSet is faster than calling mateconf_engine_set() for each value. In the future, MateConfChangeSet may also represent an atomic transaction, where all or none of the values are set; however, for now the operation is not atomic.

Functions

MateConfChangeSetForeachFunc ()

void
(*MateConfChangeSetForeachFunc) (MateConfChangeSet *cs,
                                 const gchar *key,
                                 MateConfValue *value,
                                 gpointer user_data);

The type of a function passed to mateconf_change_set_foreach(). The cs argument is the MateConfChangeSet you're iterating over. key is a key in the change set. value is the value the key will be set to, or NULL if the key will be unset. user_data is the user data passed to mateconf_change_set_foreach().

Parameters

cs

the MateConfChangeSet being iterated over.

 

key

the current key.

 

value

the current value, or NULL.

 

user_data

user data passed to mateconf_change_set_foreach().

 

mateconf_engine_commit_change_set ()

gboolean
mateconf_engine_commit_change_set (MateConfEngine *conf,
                                   MateConfChangeSet *cs,
                                   gboolean remove_committed,
                                   GError **err);

Applies the changes in the change set to the MateConfEngine passed as the first argument. If remove_committed is TRUE, then any successfully-committed changes are removed from the change set. If remove_committed is FALSE, the MateConfChangeSet is left unmodified.

If any set or unset operation results in an error, then processing terminates and the error is returned in err (unless err was NULL). If remove_committed was TRUE, then all the changes committed before the error occurred will have been removed from the set. If any error occurs, FALSE is returned.

Parameters

conf

a MateConfEngine.

 

cs

a MateConfChangeSet.

 

remove_committed

whether to remove successfully-committed changes from the set

 

err

the return location for an allocated GError, or NULL to ignore errors.

 

Returns

TRUE on success, FALSE if an error occurs.


mateconf_engine_reverse_change_set ()

MateConfChangeSet *
mateconf_engine_reverse_change_set (MateConfEngine *conf,
                                    MateConfChangeSet *cs,
                                    GError **err);

Creates a change set that would reverse cs. That is, for each change in cs, save the current state of that key in the returned change set.

Parameters

conf

a MateConfEngine.

 

cs

the MateConfChangeSet to be reverted.

 

err

the return location for an allocated GError, or NULL to ignore errors.

 

Returns

the modified MateConfChangeSet.


mateconf_engine_change_set_from_currentv ()

MateConfChangeSet *
mateconf_engine_change_set_from_currentv
                               (MateConfEngine *conf,
                                const gchar **keys,
                                GError **err);

Creates a change set that will change the keys in NULLterminated array keys to their current state.

Parameters

conf

a MateConfEngine.

 

keys

NULLterminated array of key names.  

err

the return location for an allocated GError, or NULL to ignore errors.

 

Returns

the newly allocated MateConfChangeSet.


mateconf_engine_change_set_from_current ()

MateConfChangeSet *
mateconf_engine_change_set_from_current
                               (MateConfEngine *conf,
                                GError **err,
                                const gchar *first_key,
                                ...);

Convenient Varags version of mateconf_engine_change_set_from_current().

Parameters

conf

a MateConfEngine.

 

err

the return location for an allocated GError, or NULL to ignore errors.

 

first_key

the first key, a char* value.

 

Returns

the newly allocated MateConfChangeSet.


mateconf_change_set_new ()

MateConfChangeSet *
mateconf_change_set_new (void);

Creates a new, empty MateConfChangeSet. The caller assumes one reference count, and must call mateconf_change_set_unref() eventually.

Returns

a new MateConfChangeSet.


mateconf_change_set_ref ()

MateConfChangeSet *
mateconf_change_set_ref (MateConfChangeSet *cs);

Increases the reference count of a MateConfChangeSet by one.

Parameters

Returns

the referenced MateConfChangeSet.


mateconf_change_set_unref ()

void
mateconf_change_set_unref (MateConfChangeSet *cs);

Decreases the reference count of a MateConfChangeSet by one. If the reference count reaches 0, destroys the MateConfChangeSet.

Parameters


mateconf_change_set_clear ()

void
mateconf_change_set_clear (MateConfChangeSet *cs);

Clears all changes from a MateConfChangeSet, so that committing the change set would have no effect.

Parameters


mateconf_change_set_size ()

guint
mateconf_change_set_size (MateConfChangeSet *cs);

Returns the size of the changeset, a guint value.

Parameters

Returns

the size, a guint value.


mateconf_change_set_remove ()

void
mateconf_change_set_remove (MateConfChangeSet *cs,
                            const gchar *key);

Removes a change from a MateConfChangeSet. The key given as the key argument will not be modified if this change set is committed. If key is not in the change set, this function has no effect.

Parameters

cs

a MateConfChangeSet.

 

key

key to remove from the change set.

 

mateconf_change_set_foreach ()

void
mateconf_change_set_foreach (MateConfChangeSet *cs,
                             MateConfChangeSetForeachFunc func,
                             gpointer user_data);

Iterates over a MateConfChangeSet by calling a MateConfChangeSetForeachFunc for each change in the set. See the description of MateConfChangeSetForeachFunc for details. You may not call mateconf_change_set_remove() during the iteration, because you'll confuse the internal data structures and cause memory corruption.

Parameters

cs

a MateConfChangeSet.

 

func

function to call for each change in the change set.

[scope call]

user_data

user data to pass to the MateConfChangeSetForeachFunc.

 

mateconf_change_set_check_value ()

gboolean
mateconf_change_set_check_value (MateConfChangeSet *cs,
                                 const gchar *key,
                                 MateConfValue **value_retloc);

Looks up the hash table associated with the MateConfChangeSet for the key key. If the key is found , the value is set in value_retloc.

Parameters

cs

a MateConfChangeSet.

 

key

the key to be searched in the changeset.

 

value_retloc

a MateConfValue ** to hold the key, if found.

 

Returns

TRUE on finding the key, FALSE if key is not found.


mateconf_change_set_set ()

void
mateconf_change_set_set (MateConfChangeSet *cs,
                         const gchar *key,
                         MateConfValue *value);

Adds a "set" operation to a change set. This function is similar to mateconf_engine_set(), except that no errors can occur (errors occur later, when you try to commit the change set).

Parameters

cs

a MateConfChangeSet.

 

key

the key to change.

 

value

the value to change the key to.

 

mateconf_change_set_set_nocopy ()

void
mateconf_change_set_set_nocopy (MateConfChangeSet *cs,
                                const gchar *key,
                                MateConfValue *value);

Like mateconf_change_set_set(), except that the MateConfChangeSet takes ownership of the MateConfValue. You should not use the value again. It will be destroyed when the change is removed from the MateConfChangeSet, the change is modified, or the MateConfChangeSet is destroyed.

Parameters

cs

a MateConfChangeSet.

 

key

the key to change.

 

value

the new value of key .

 

mateconf_change_set_unset ()

void
mateconf_change_set_unset (MateConfChangeSet *cs,
                           const gchar *key);

Adds an "unset" operation to a MateConfChangeSet. This function schedules a mateconf_engine_unset().

Parameters

cs

a MateConfChangeSet.

 

key

the key to unset.

 

mateconf_change_set_set_float ()

void
mateconf_change_set_set_float (MateConfChangeSet *cs,
                               const gchar *key,
                               gdouble val);

Adds a "set" operation; takes a gdouble argument, so you can avoid creating a MateConfValue.

Parameters

cs

a MateConfChangeSet.

 

key

the key to set.

 

val

the new value of key .

 

mateconf_change_set_set_int ()

void
mateconf_change_set_set_int (MateConfChangeSet *cs,
                             const gchar *key,
                             gint val);

Adds a "set" operation; takes a gint argument, so you can avoid creating a MateConfValue.

Parameters

cs

a MateConfChangeSet.

 

key

the key to set.

 

val

the new value of key .

 

mateconf_change_set_set_string ()

void
mateconf_change_set_set_string (MateConfChangeSet *cs,
                                const gchar *key,
                                const gchar *val);

Adds a "set" operation; takes a gchar* argument, so you can avoid creating a MateConfValue.

Parameters

cs

a MateConfChangeSet.

 

key

the key to set.

 

val

the new value of key .

 

mateconf_change_set_set_bool ()

void
mateconf_change_set_set_bool (MateConfChangeSet *cs,
                              const gchar *key,
                              gboolean val);

Adds a "set" operation; takes a gboolean argument, so you can avoid creating a MateConfValue.

Parameters

cs

a MateConfChangeSet.

 

key

the key to set.

 

val

the new value of key .

 

mateconf_change_set_set_schema ()

void
mateconf_change_set_set_schema (MateConfChangeSet *cs,
                                const gchar *key,
                                MateConfSchema *val);

Adds a "set" operation; takes a MateConfSchema argument, so you can avoid creating a MateConfValue. The schema is copied, val is left unmodified.

Parameters

cs

a MateConfChangeSet.

 

key

the key to set.

 

val

the new value of key .

 

mateconf_change_set_set_list ()

void
mateconf_change_set_set_list (MateConfChangeSet *cs,
                              const gchar *key,
                              MateConfValueType list_type,
                              GSList *list);

Adds a "set" operation; takes a GList argument and the type of the list, so you can avoid creating a MateConfValue. This results in the list of values being set for the key.

Parameters

cs

a MateConfChangeSet.

 

key

the key to set.

 

list_type

the type of the list.

 

list

a GList containing the values to be set.

 

mateconf_change_set_set_pair ()

void
mateconf_change_set_set_pair (MateConfChangeSet *cs,
                              const gchar *key,
                              MateConfValueType car_type,
                              MateConfValueType cdr_type,
                              gconstpointer address_of_car,
                              gconstpointer address_of_cdr);

Adds a "set" operation; takes a pointer to the addresses of the pair of values, so you can avoid creating a MateConfValue. This results in the pair of values being set for the key.

Parameters

cs

a MateConfChangeSet.

 

key

the key to set.

 

car_type

the type of the pair's first field. (car)

 

cdr_type

the type of the pair's second field. (cdr)

 

address_of_car

address of the car.

 

address_of_cdr

address of the cdr.

 

mateconf_change_set_set_user_data ()

void
mateconf_change_set_set_user_data (MateConfChangeSet *cs,
                                   gpointer data,
                                   GDestroyNotify dnotify);

Sets the user_data and the destroy notification function fields of the MateConfChangeSet.

Parameters

cs

a MateConfChangeSet.

 

data

a gpointer.

 

dnotify

a pointer to the function to be called during destroy.

 

mateconf_change_set_get_user_data ()

gpointer
mateconf_change_set_get_user_data (MateConfChangeSet *cs);

Returns the user_data field of the MateConfChangeSet.

Parameters

Returns

a pointer to the user_data.

Types and Values

MateConfChangeSet

typedef struct _MateConfChangeSet MateConfChangeSet;

An opaque data type representing a set of changes to be made. A change set can contain "set" and "unset" operations.