GConf Manual | |||
---|---|---|---|
<<< Previous Page | Home | Next Page >>> |
The GConf client library is used by applications to store or retrieve configuration data. This library presents the lowest-level (but still fairly convenient) mode of access to the GConf database; the GConf database does not speak a public protocol and can not be accessed directly.
Convenience wrappers for the GConf client library are possible. Right now a nice wrapper based on the GTK+ object system exists; see the chapter called GtkObject Convenience Wrapper.
Note that this is only a brief tutorial-style introduction to the client library; have a look at the chapter called GConf Reference Documentation for a complete reference.
Error handling isn't exciting but it's unfortunately necessary. Because even the initialization of the GConf library can fail, we have to cover error handling first.
Errors are returned in a GError object. GError has two public fields: str is an error message, and num is an errno-style enumerated value with type GConfError, useful for switching on an error and taking different actions depending on the exact error that occurred.
GConf functions that potentially fail accept a GError** argument, where they store a GError object if the operation fails. If no error occurs, the location pointed to by the GError** is left unchanged. In all cases, you can pass NULL as the GError**, to ignore any errors. Needless to say, normally you should report errors instead of ignoring them.
If an error is returned, you must free it with g_error_free():
Thus, a complete error-checking sequence might work like this:
GError* err = NULL; if (!gconf_init(&err)) { fprintf(stderr, _("Failed to init GConf: %s\n"), err->message); g_error_free(err); err = NULL; } |
Error checking is slightly inconvenient to use because we have to be thread-safe; GConf originally had a system similar to errno, but that doesn't work with threads. GConf still isn't thread-safe, but the API isn't inherently unsafe.
The available values for GConfError are:
Indicates that there was no error.
Indicates that the operation fatally failed for some fairly unpredictable and idiosyncratic reason not covered by the more specific error values. The error message will give details.
The gconfd configuration server could not be contacted, and we couldn't or didn't respawn it for whatever reason. The error message may give more details. This probably means either a bug in gconfd or a hosed local configuration.
User was denied permission to access some resource at some point; perhaps a file in a file-based configuration backend, perhaps some authentication tokens are wrong. The error message will give more details.
A configuration source address was invalid.
A configuration key was invalid.
Something had to be parsed, and it couldn't be. Typically, a string representation of a config value found in a config file or obtained from the user. Error message will often have more details.
Typically means that the text files or binary database used by some backend have gotten hosed. Most backends will try to self-repair, within reason. If they can't they will bail with this error.
Some routines in the GConf libraries impose type constraints; if these are violated you get this error. For example, gconf_engine_get_int() returns this error if the value found is actually a string.
This error is returned if you try to perform a key operation on a name that turns out to be a directory. Some backends don't check for this error, they just report that the key isn't set...
This error is returned if you try to perform a directory operation on a name that turns out to be a key. Some backends don't check for this error...
This means that you tried to set a value, and a read-only configuration source found before the first user-writable source in the path has already set the value. That is, setting the value would have no effect because the read-only source's setting would override the new value. You should report to the user that their setting will not take effect.
gconf_error_new() is used inside the library and inside the library backends. It is typically not useful to clients. It simply creates a new error, from a GConfError and a printf()-style format and variable argument list.