Next: , Previous: Overview, Up: Top

2 GConfClient

convenience wrapper

2.1 Overview

<g-conf-client> adds the following features to plain GConf:

A client-side cache for a specified list of directories you're interested in. You can "preload" entire directories into the cache, speeding things up even more.

Some automatic error handling, if you request it.

Signals when a value changes or an error occurs.

If you use <g-conf-client>, you should not use the underlying <g-conf-engine> directly, or you'll break things. This is why there's no gconf-client-get-engine function; in fact, if you create the <g-conf-client> with gconf-client-get-default, there is no (legitimate) way to obtain a pointer to the underlying <g-conf-engine>. If you create a <g-conf-client> from an existing engine, you'll have to be disciplined enough to avoid using that engine directly.

This is all a white lie; some direct <g-conf-engine> operations are safe. But it's complicated to know which, and if an operation isn't safe the resulting bugs will mangle the cache and cause weird bugs at an indeterminate time in the future; you don't want to risk this situation.

A <g-conf-client> has a list of directories that it "watches." These directories are optionally pre-loaded into the cache, and monitored in order to emit the <value-changed> signal. The <g-conf-client> can also be used to access directories not in the list, but those directories won't be preloaded and the "value_changed" signal won't be emitted for them.

There are two error-related signals in <g-conf-client>. The first is plain "error"; it's emitted anytime an error occurs. The second is "unreturned_error"; this signal is emitted if you pass as the <g-error>** to any <g-conf-client> function. The idea is that you can have a global error handler attached to the "unreturned_error" signal; if you want to use this handler, you don't need to use the normal GConf error handling mechanism. However, if you ever need to handle errors for a specific function call, you can override the global handler by passing a non-<g-error>** to the function. If you want an error handler that's always invoked, use the "error" signal.

The "value_changed" signal is emitted whenever the server notifies your client program that a value has changed in the GConf database. There's one problem with this signal: the signal handler has to use strcmp to determine whether the changed value is the one it was interested in. If you are interested in lots of values, then every time a value changes you'll be making lots of calls to strcmp and getting O(n) performance. gconf-client-notify-add is a superior interface in most cases for this reason. Note that calling gconf-client-set and its relatives will cause "value_changed" to be emitted, but "value_changed" is also emitted if another process changes the value.

Most of the <g-conf-client> interface mirrors the functions you'd use to manipulate a <g-conf-engine> (gconf-engine-get and gconf-client-get, for example). These should all work just like the <g-conf-engine> versions, except that they use the cache from <g-conf-client> and emit the <g-conf-client> signals.

As always with GConf, applications based on <g-conf-client> should use a model-controller-view architecture. Typically, this means that areas of your application affected by a setting will monitor the relevant key and update themselves when necessary. The preferences dialog will simply change keys, allowing GConf to notify the rest of the application that changes have occurred. Here the application proper is the "view," GConf is the "model", and the preferences dialog is the "controller." In no case should you do this: This breaks if a setting is changed outside your application&#x2014;or even from a different part of your application. The correct way (in pseudo-code) is: See the example programs that come with GConf for more details. 

     
      gconf_client_set(client, key, value);
      application_update_to_reflect_setting();

     
      /* At application startup */
      gconf_client_notify_add(client, key, application_update_to_reflect_setting, data);
     
      /* From preferences dialog */
      gconf_client_set(client, key, value);

2.2 Usage

— Function: gconf-client-get-default ⇒  (ret <g-conf-client>)

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

It's important to call g-type-init before using this GObject, to initialize the type system.

ret
a new <g-conf-client>. g-object-unref when you're done.
— Function: gconf-client-add-dir (self <g-conf-client>) (dir mchars) (preload <g-conf-client-preload-type>)

Add a directory to the list of directories the <g-conf-client> 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 <g-conf-client> preload its contents; see <g-conf-client-preload-type> 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.

client
a <g-conf-client>.
dir
directory to add to the list.
preload
degree of preload.
err
the return location for an allocated <g-error>, or #f to ignore errors.
— Function: gconf-client-remove-dir (self <g-conf-client>) (dir mchars)

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.

client
a <g-conf-client>.
dir
directory to remove.
err
the return location for an allocated <g-error>, or #f to ignore errors.
— Function: gconf-client-notify-add (self <g-conf-client>) (namespace_section mchars) (proc scm) ⇒  (ret unsigned-int)

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, <g-conf-client> requests server notification for directories added with gconf-client-add-dir and keeps the list of <g-conf-client-notify-func> 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 <g-conf-client-notify-func> for details on how the notification function is called.

client
a <g-conf-client>.
namespace-section
where to listen for changes.
func
function to call when changes occur.
user-data
user data to pass to func.
destroy-notify
function to call on user-data when the notify is removed or the <g-conf-client> is destroyed, or #f for none.
err
the return location for an allocated <g-error>, or #f to ignore errors.
ret
a connection ID for removing the notification.
— Function: gconf-client-notify-remove (self <g-conf-client>) (cnxn unsigned-int)

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.

client
a <g-conf-client>.
cnxn
connection ID.
— Function: gconf-client-notify (self <g-conf-client>) (key mchars)

Emits the "value-changed" signal and notifies listeners as if key had been changed

client
a <g-conf-client>.
key
the key that has changed.

Since 2.4.

— Function: gconf-client-set-error-handling (self <g-conf-client>) (mode <g-conf-client-error-handling-mode>)

Controls the default error handling for <g-conf-client>. See <g-conf-client-error-handling-mode> and <g-conf-client-parent-window-func> for details on this.

client
a <g-conf-client>.
mode
error handling mode.
— Function: gconf-client-clear-cache (self <g-conf-client>)

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

client
a <g-conf-client>.
— Function: gconf-client-preload (self <g-conf-client>) (dirname mchars) (type <g-conf-client-preload-type>)

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.

client
a <g-conf-client>.
dirname
directory to preload.
type
degree of preload.
err
the return location for an allocated <g-error>, or #f to ignore errors.
— Function: gconf-client-set (self <g-conf-client>) (key mchars) (val <g-conf-value>)

Sets the value of a configuration key. Just like gconf-engine-set, but uses <g-conf-client> caching and error-handling features. The val argument will not be modified.

client
a <g-conf-client>.
key
key to set.
val
new value.
err
the return location for an allocated <g-error>, or #f to ignore errors.
— Function: gconf-client-get (self <g-conf-client>) (key mchars) ⇒  (ret <g-conf-value>)

Gets the value of a configuration key. Just like gconf-engine-get, but uses <g-conf-client> caching and error-handling features.

client
a <g-conf-client>.
key
key to get.
err
the return location for an allocated <g-error>, or #f to ignore errors.
ret
newly-allocated <g-conf-value>, or #f if unset and no default exists.
— Function: gconf-client-get-without-default (self <g-conf-client>) (key mchars) ⇒  (ret <g-conf-value>)

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.

client
a <g-conf-client>.
key
key to get.
err
the return location for an allocated <g-error>, or #f to ignore errors.
ret
newly-allocated <g-conf-value>, or #f if unset (even if a default exists).
— Function: gconf-client-unset (self <g-conf-client>) (key mchars) ⇒  (ret bool)

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 <g-conf-client> caching and error-handling features.

client
a <g-conf-client>.
key
key to unset.
err
the return location for an allocated <g-error>, or #f to ignore errors.
ret
#t on success, #f on error.
— Function: gconf-client-recursive-unset (self <g-conf-client>) (key mchars) (flags unsigned-int) ⇒  (ret bool)

Unsets all keys below key, including key itself. If any unset fails, continues on to unset as much as it can. The first failure is returned in err. Just like gconf-engine-recursive-unset, but uses <g-conf-client> caching and error-handling features.

client
a <g-conf-client>.
key
a key or directory name to be unset.
flags
change how the unset is done.
err
the return location for an allocated <g-error>, or #f to ignore errors.
ret
#t on success, #f on error.

Since 2.4.

— Function: gconf-client-all-dirs (self <g-conf-client>) (dir mchars) ⇒  (ret gslist-of)

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 <g-conf-client> caching and error-handling features.

client
a <g-conf-client>.
dir
directory to get subdirectories from.
err
the return location for an allocated <g-error>, or #f to ignore errors.
ret
List of allocated subdirectory names.
— Function: gconf-client-suggest-sync (self <g-conf-client>)

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.

client
a <g-conf-client>.
err
the return location for an allocated <g-error>, or #f to ignore errors.
— Function: gconf-client-dir-exists (self <g-conf-client>) (dir mchars) ⇒  (ret bool)

Queries whether the directory dir exists in the GConf database. Returns #t or #f. Just like gconf-engine-dir-exists, but uses <g-conf-client> caching and error-handling features.

client
a <g-conf-client>.
dir
directory to check for
err
the return location for an allocated <g-error>, or #f to ignore errors.
ret
#t or #f.
— Function: gconf-client-key-is-writable (self <g-conf-client>) (key mchars) ⇒  (ret bool)

Checks whether the key is writable.

client
a <g-conf-client>.
key
the value to be changed.
err
the return location for an allocated <g-error>, or #f to ignore errors.
ret
#t if the key is writable, #f if the key is read only.
— Function: gconf-client-value-changed (self <g-conf-client>) (key mchars) (value <g-conf-value>)

Emits the "value_changed" signal. Rarely useful.

client
a <g-conf-client>.
key
key to pass to signal handlers.
value
value of key to pass to signal handlers.