C Language Client Library

Table of Contents
Error Handling
The GConfEngine object
The GConfValue Datatype
Reading/Writing Configuration Values

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.

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

Error handling isn't exciting but it's unfortunately necessary. GConf uses the standard GError feature from GLib; if you have never read the documentation on GError, you should do so right away.

When using GConfClient routines, it's OK to pass NULL for the error argument most of the time; it has a default error handler that will be run.

The available error codes are:

GCONF_SUCCESS	Indicates that there was no error.
GCONF_FAILED	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.
GCONF_NO_SERVER	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.
GCONF_NO_PERMISSION	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.
GCONF_BAD_ADDRESS	A configuration source address was invalid.
GCONF_BAD_KEY	A configuration key was invalid.
GCONF_PARSE_ERROR	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.
GCONF_CORRUPT	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.
GCONF_TYPE_MISMATCH	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.
GCONF_IS_DIR	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...
GCONF_IS_KEY	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...
GCONF_OVERRIDDEN	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.