Synopsis

enum GConfClientPreloadType

typedef enum { /*< prefix=GCONF_CLIENT >*/
  GCONF_CLIENT_PRELOAD_NONE,     /* don't preload anything */
  GCONF_CLIENT_PRELOAD_ONELEVEL, /* load entries directly under the directory. */
  GCONF_CLIENT_PRELOAD_RECURSIVE /* recurse the directory tree; possibly quite expensive! */
} GConfClientPreloadType;

The GConfClientPreloadType is used to tell GConfClient how to preload one of its directories. As a rule of thumb, if you plan to get the value of almost all the keys in a directory, preloading that directory will probably enhance performance. If you plan to use only half the keys, preloading is likely a bad idea. GCONF_CLIENT_PRELOAD_NONE specifies that no preload occurs, GCONF_CLIENT_PRELOAD_ONELEVEL loads the immediate children of the directory, GCONF_CLIENT_PRELOAD_RECURSIVE loads all children of the directory and its subdirectories, recursively.

enum GConfClientErrorHandlingMode

typedef enum { /*< prefix=GCONF_CLIENT >*/
  GCONF_CLIENT_HANDLE_NONE,
  GCONF_CLIENT_HANDLE_UNRETURNED,
  GCONF_CLIENT_HANDLE_ALL
} GConfClientErrorHandlingMode;

GConfClientErrorHandlingMode is used to control GConfClient's default error handling. GConfClient can pop up a dialog in the default signal handler for "error" or "unreturned_error." You can specify that no errors are handled, only unreturned errors are handled, or all errors are handled with this enumeration. You can prevent specific errors from being handled automatically by stopping the signal emission before the default signal handler is called (see the GTK+ documentation, gtk_signal_emit_stop_by_name() for example).

GConfClientNotifyFunc ()

void        (*GConfClientNotifyFunc)        (GConfClient *client,
                                             guint cnxn_id,
                                             GConfEntry *entry,
                                             gpointer user_data);

This is the signature of a user function added with gconf_client_notify_add(). The notify function is invoked when the value of a key changes. The value argument is the new value, or NULL if the key was unset. The value argument should not be modified, and should be copied if you want to keep it around (the GConfClient will destroy it sometime after your notify function is called).

GConfClientErrorHandlerFunc ()

void        (*GConfClientErrorHandlerFunc)  (GConfClient *client,
                                             GError *error);

GCONF_CLIENT()

#define GCONF_CLIENT(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), GCONF_TYPE_CLIENT, GConfClient))

Casts a pointer to a GConfClient*.

gconf_client_get_default ()

GConfClient* gconf_client_get_default       (void);

Creates a new GConfClient using the default GConfEngine. Normally this is the engine you want. If someone else is already using the default GConfClient, this function returns the same one they're using, but with the reference count incremented. So you have to unref either way.

gconf_client_get_for_engine ()

GConfClient* gconf_client_get_for_engine    (GConfEngine *engine);

Creates a new GConfClient with a specific GConfEngine. Only specialized configuration-related programs should need to call this function. The returned GConfClient should be unref'd when you're done with g_object_unref(). Remember to avoid using the GConfEngine directly once you have a GConfClient wrapper.

gconf_client_add_dir ()

void        gconf_client_add_dir            (GConfClient *client,
                                             const gchar *dir,
                                             GConfClientPreloadType preload,
                                             GError **err);

Add a directory to the list of directories the GConfClient will watch. Any changes to keys below this directory will cause the "value_changed" signal to be emitted. When you add the directory, you can request that the GConfClient preload its contents; see GConfClientPreloadType for details.

Added directories may not overlap. That is, if you add "/foo", you may not add "/foo/bar". However you can add "/foo" and "/bar". You can also add "/foo" multiple times; if you add a directory multiple times, it will not be removed until you call gconf_client_remove_dir() an equal number of times.

gconf_client_remove_dir ()

void        gconf_client_remove_dir         (GConfClient *client,
                                             const gchar *dir,
                                             GError **err);

Remove a directory from the list created with gconf_client_add_dir(). If any notifications have been added below this directory with gconf_client_notify_add(), those notifications will be disabled until you re-add the removed directory. Note that if a directory has been added multiple times, you must remove it the same number of times before the remove takes effect.

gconf_client_notify_add ()

guint       gconf_client_notify_add         (GConfClient *client,
                                             const gchar *namespace_section,
                                             GConfClientNotifyFunc func,
                                             gpointer user_data,
                                             GFreeFunc destroy_notify,
                                             GError **err);

Request notification of changes to namespace_section. This includes the key namespace_section itself, and any keys below it (the behavior is identical to gconf_engine_notify_add(), but while gconf_engine_notify_add() places a notification request on the server for every notify function, GConfClient requests server notification for directories added with gconf_client_add_dir() and keeps the list of GConfClientNotifyFunc on the client side).

For the notification to happen, namespace_section must be equal to or below one of the directories added with gconf_client_add_dir(). You can still call gconf_client_notify_add() for other directories, but no notification will be received until you add a directory above or equal to namespace_section. One implication of this is that gconf_client_remove_dir() temporarily disables notifications that were below the removed directory.

The function returns a connection ID you can use to call gconf_client_notify_remove().

See the description of GConfClientNotifyFunc for details on how the notification function is called.

gconf_client_notify_remove ()

void        gconf_client_notify_remove      (GConfClient *client,
                                             guint cnxn);

Remove a notification using the ID returned from gconf_client_notify_add(). Invokes the destroy notify function on the notification's user data, if appropriate.

gconf_client_set_error_handling ()

void        gconf_client_set_error_handling (GConfClient *client,
                                             GConfClientErrorHandlingMode mode);

Controls the default error handling for GConfClient. See GConfClientErrorHandlingMode and GConfClientParentWindowFunc for details on this.

gconf_client_set_global_default_error_handler ()

void        gconf_client_set_global_default_error_handler
                                            (GConfClientErrorHandlerFunc func);

gconf_client_clear_cache ()

void        gconf_client_clear_cache        (GConfClient *client);

Dumps everything out of the GConfClient client-side cache. If you know you're done using the GConfClient for a while, you can call this function to save some memory.

gconf_client_preload ()

void        gconf_client_preload            (GConfClient *client,
                                             const gchar *dirname,
                                             GConfClientPreloadType type,
                                             GError **err);

Preloads a directory. Normally you do this when you call gconf_client_add_dir(), but if you've called gconf_client_clear_cache() there may be a reason to do it again.

gconf_client_set ()

void        gconf_client_set                (GConfClient *client,
                                             const gchar *key,
                                             const GConfValue *val,
                                             GError **err);

Sets the value of a configuration key. Just like gconf_engine_set(), but uses GConfClient caching and error-handling features. The val argument will not be modified.

gconf_client_get ()

GConfValue* gconf_client_get                (GConfClient *client,
                                             const gchar *key,
                                             GError **err);

Gets the value of a configuration key. Just like gconf_engine_get(), but uses GConfClient caching and error-handling features.

gconf_client_get_without_default ()

GConfValue* gconf_client_get_without_default
                                            (GConfClient *client,
                                             const gchar *key,
                                             GError **err);

Gets the value of a configuration key. Just like gconf_client_get() but doesn't look for a default value if the key is unset.

gconf_client_get_entry ()

GConfEntry* gconf_client_get_entry          (GConfClient *client,
                                             const gchar *key,
                                             const gchar *locale,
                                             gboolean use_schema_default,
                                             GError **err);

Obtains the full GConfEntry for a value. Just like gconf_engine_get_entry(), but uses GConfClient caching and error-handling features.

gconf_client_get_default_from_schema ()

GConfValue* gconf_client_get_default_from_schema
                                            (GConfClient *client,
                                             const gchar *key,
                                             GError **err);

Returns the default value stored in the key's schema, if the key has a schema associated and the schema exists and the schema contains a default value. Note that gconf_client_get(), gconf_engine_client_string(), and so on already return the default value if no other value is found, so normally you do not need this function. This function is just for convenience; you could also get the GConfMetaInfo for the key, read the schema name from there, then look up the schema by name and extract the default value. Just like gconf_engine_get_default_from_schema(), but uses GConfClient caching and error-handling features.

gconf_client_unset ()

gboolean    gconf_client_unset              (GConfClient *client,
                                             const gchar *key,
                                             GError **err);

Unsets the value of key; if key is already unset, has no effect. An error of note is GCONF_OVERRIDDEN, indicating that the system administrator has "forced" a value for this key. Just like gconf_engine_unset(), but uses GConfClient caching and error-handling features.

gconf_client_all_entries ()

GSList*     gconf_client_all_entries        (GConfClient *client,
                                             const gchar *dir,
                                             GError **err);

Lists the key-value pairs in dir. Does not list subdirectories; for that use gconf_client_all_dirs(). The returned list contains GConfEntry objects. A GConfEntry contains an absolute key and a value. The list is not recursive, it contains only the immediate children of dir. To free the returned list, gconf_entry_free() each list element, then g_slist_free() the list itself. Just like gconf_engine_all_entries(), but uses GConfClient caching and error-handling features.

gconf_client_all_dirs ()

GSList*     gconf_client_all_dirs           (GConfClient *client,
                                             const gchar *dir,
                                             GError **err);

Lists the subdirectories in dir. The returned list contains allocated strings. Each string is the absolute path of a subdirectory. You should g_free() each string in the list, then g_slist_free() the list itself. Just like gconf_engine_all_dirs(), but uses GConfClient caching and error-handling features.

gconf_client_suggest_sync ()

void        gconf_client_suggest_sync       (GConfClient *client,
                                             GError **err);

Suggests to gconfd that you've just finished a block of changes, and it would be an optimal time to sync to permanent storage. This is only a suggestion; and gconfd will eventually sync even if you don't call gconf_engine_suggest_sync(). This function is just a "hint" provided to gconfd to maximize efficiency and minimize data loss. Just like gconf_engine_suggest_sync().

gconf_client_dir_exists ()

gboolean    gconf_client_dir_exists         (GConfClient *client,
                                             const gchar *dir,
                                             GError **err);

Queries whether the directory dir exists in the GConf database. Returns TRUE or FALSE. Just like gconf_engine_dir_exists(), but uses GConfClient caching and error-handling features.

gconf_client_get_float ()

gdouble     gconf_client_get_float          (GConfClient *client,
                                             const gchar *key,
                                             GError **err);

Requests the floating point number (GCONF_VALUE_FLOAT) stored at key. Automatically performs type-checking, so if a non-float is stored at key, an error is returned. On error, or if key is unset, 0.0 is returned. Just like gconf_engine_get_float(), but uses GConfClient caching and error-handling features.

gconf_client_get_int ()

gint        gconf_client_get_int            (GConfClient *client,
                                             const gchar *key,
                                             GError **err);

Requests the integer (GCONF_VALUE_INT) stored at key. Automatically performs type-checking, so if a non-integer is stored at key, an error is returned. On error, or if key is unset, 0 is returned. Just like gconf_engine_get_int(), but uses GConfClient caching and error-handling features.

gconf_client_get_string ()

gchar*      gconf_client_get_string         (GConfClient *client,
                                             const gchar *key,
                                             GError **err);

Requests the string (GCONF_VALUE_STRING) stored at key. Automatically performs type-checking, so if a non-string is stored at key, an error is returned. On error, or if key is unset, NULL is returned. Just like gconf_engine_get_string(), but uses GConfClient caching and error-handling features.

gconf_client_get_bool ()

gboolean    gconf_client_get_bool           (GConfClient *client,
                                             const gchar *key,
                                             GError **err);

Requests the boolean value (GCONF_VALUE_BOOL) stored at key. Automatically performs type-checking, so if a non-bool is stored at key, an error is returned. On error, or if key is unset, FALSE is returned. Just like gconf_engine_get_bool(), but uses GConfClient caching and error-handling features.

gconf_client_get_schema ()

GConfSchema* gconf_client_get_schema        (GConfClient *client,
                                             const gchar *key,
                                             GError **err);

Requests the schema (GCONF_VALUE_SCHEMA) stored at key. Automatically performs type-checking, so if a non-schema is stored at key, an error is returned. If no value is set or an error occurs, NULL is returned. Just like gconf_engine_get_schema(), but uses GConfClient caching and error-handling features.

gconf_client_get_list ()

GSList*     gconf_client_get_list           (GConfClient *client,
                                             const gchar *key,
                                             GConfValueType list_type,
                                             GError **err);

Requests the list (GCONF_VALUE_LIST) stored at key. Automatically performs type-checking, so if a non-list is stored at key, or the list does not contain elements of type list_type, an error is returned. If no value is set or an error occurs, NULL is returned. Note that NULL is also the empty list, so if you need to distinguish the empty list from an unset value, you must use gconf_client_get() to obtain a raw GConfValue.

Remember that GConf lists can only store primitive types: GCONF_VALUE_FLOAT, GCONF_VALUE_INT, GCONF_VALUE_BOOL, GCONF_VALUE_STRING, GCONF_VALUE_SCHEMA. Also remember that lists must be uniform, you may not mix types in the same list.

The type of the list elements depends on list_type. A GConfValue with type GCONF_VALUE_LIST normally stores a list of more GConfValue objects. gconf_client_get_list() automatically converts to primitive C types. Thus, the list->data fields in the returned list contain:

In the GCONF_VALUE_FLOAT and GCONF_VALUE_STRING cases, you must g_free() each list element. In the GCONF_VALUE_SCHEMA case you must gconf_schema_free() each element. In all cases you must free the list itself with g_slist_free(). Just like gconf_engine_get_list(), but uses GConfClient caching and error-handling features.

gconf_client_get_pair ()

gboolean    gconf_client_get_pair           (GConfClient *client,
                                             const gchar *key,
                                             GConfValueType car_type,
                                             GConfValueType cdr_type,
                                             gpointer car_retloc,
                                             gpointer cdr_retloc,
                                             GError **err);

Requests the pair (GCONF_VALUE_PAIR) stored at key. Automatically performs type-checking, so if a non-pair is stored at key, or the pair does not have the right car_type and cdr_type, an error is returned. Remember that the car of a pair is its first value, and the cdr is its second value, in the Lisp tradition.

Remember that GConf pairs can only store primitive types: GCONF_VALUE_FLOAT, GCONF_VALUE_INT, GCONF_VALUE_BOOL, GCONF_VALUE_STRING, GCONF_VALUE_SCHEMA.

gconf_client_get_pair() stores the two fields of the pair in the locations pointed to by car_retloc and cdr_retloc. The type of these pointers depends on the corresponding car_type and cdr_type:

In the GCONF_VALUE_STRING case, you must g_free() the string(s) stored in the return location(s). In the GCONF_VALUE_SCHEMA case you must gconf_schema_free() the returned schema. If there's an error or the value is unset, car_retloc and cdr_retloc are left unchanged.

gconf_client_get_pair() returns TRUE on success.

An example of gconf_client_get_pair() in action:

gdouble car = 10.0;
gchar* cdr  = NULL; 
GError* error = NULL;

if (!gconf_client_get_pair(conf, "/foo", 
                    GCONF_VALUE_FLOAT,
                    GCONF_VALUE_STRING, 
                    &car, &cdr, &error))
  {
    /* Note: car/cdr should be untouched, because an error occurred */
    g_assert(error != NULL);
    fprintf(stderr, "Error: s\n", error->message);
    g_error_free(error);
    error = NULL;
  }
else
  {
    /* Note: car/cdr may be untouched even though there was no error, 
       if no value was set for "/foo"
     */
    printf("Found pair (g,s)\n", car, cdr);
    if (cdr != NULL)
      g_free(cdr);
  }

gconf_client_set_float ()

gboolean    gconf_client_set_float          (GConfClient *client,
                                             const gchar *key,
                                             gdouble val,
                                             GError **err);

Change the value of key to val. Automatically creates the key if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store a float (GCONF_VALUE_FLOAT), gconf_client_set_float() will fail. Just like gconf_engine_set(), but uses GConfClient caching and error-handling features.

gconf_client_set_int ()

gboolean    gconf_client_set_int            (GConfClient *client,
                                             const gchar *key,
                                             gint val,
                                             GError **err);

Change the value of key to val. Automatically creates the key if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store an integer (GCONF_VALUE_INT), gconf_client_set_int() will fail. Just like gconf_engine_set(), but uses GConfClient caching and error-handling features.

gconf_client_set_string ()

gboolean    gconf_client_set_string         (GConfClient *client,
                                             const gchar *key,
                                             const gchar *val,
                                             GError **err);

Change the value of key to val. Automatically creates the key if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store a string (GCONF_VALUE_STRING), gconf_client_set_string() will fail. Just like gconf_engine_set(), but uses GConfClient caching and error-handling features.

gconf_client_set_bool ()

gboolean    gconf_client_set_bool           (GConfClient *client,
                                             const gchar *key,
                                             gboolean val,
                                             GError **err);

Change the value of key to val. Automatically creates the key if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but but doesn't store a boolean (GCONF_VALUE_BOOL), gconf_client_set_bool() will fail. Just like gconf_engine_set(), but uses GConfClient caching and error-handling features.

gconf_client_set_schema ()

gboolean    gconf_client_set_schema         (GConfClient *client,
                                             const gchar *key,
                                             const GConfSchema *val,
                                             GError **err);

Change the value of key to val. Automatically creates the key if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store a schema value (GCONF_VALUE_SCHEMA), gconf_client_set_schema() will fail. Just like gconf_engine_set(), but uses GConfClient caching and error-handling features.

gconf_client_set_list ()

gboolean    gconf_client_set_list           (GConfClient *client,
                                             const gchar *key,
                                             GConfValueType list_type,
                                             GSList *list,
                                             GError **err);

gconf_client_set_pair ()

gboolean    gconf_client_set_pair           (GConfClient *client,
                                             const gchar *key,
                                             GConfValueType car_type,
                                             GConfValueType cdr_type,
                                             gconstpointer address_of_car,
                                             gconstpointer address_of_cdr,
                                             GError **err);

gconf_client_error ()

void        gconf_client_error              (GConfClient *client,
                                             GError *error);

Emits the "error" signal. Rarely useful.

gconf_client_unreturned_error ()

void        gconf_client_unreturned_error   (GConfClient *client,
                                             GError *error);

Emits the "unreturned_error" signal. Rarely useful.

gconf_client_value_changed ()

void        gconf_client_value_changed      (GConfClient *client,
                                             const gchar *key,
                                             GConfValue *value);

Emits the "value_changed" signal. Rarely useful.

gconf_client_reverse_change_set ()

GConfChangeSet* gconf_client_reverse_change_set
                                            (GConfClient *client,
                                             GConfChangeSet *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.

gconf_client_change_set_from_currentv ()

GConfChangeSet* gconf_client_change_set_from_currentv
                                            (GConfClient *client,
                                             const gchar **keys,
                                             GError **err);

Creates a change set that will change the keys in NULL-terminated array keys to their current state. Use this to save the current state of a collection of keys; then you can later revert to the current state by committing the returned change set.

gconf_client_change_set_from_current ()

GConfChangeSet* gconf_client_change_set_from_current
                                            (GConfClient *client,
                                             GError **err,
                                             const gchar *first_key,
                                             ...);

Convenient varargs version of gconf_client_change_set_from_currentv().

gconf_client_commit_change_set ()

gboolean    gconf_client_commit_change_set  (GConfClient *client,
                                             GConfChangeSet *cs,
                                             gboolean remove_committed,
                                             GError **err);