C Language Client Library

Table of Contents
Error Handling
Initialization
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.

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

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():

#include <gconf/gconf.h>
void g_error_free (GError* error);

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;
            }
        
Note that gconf_init() returns TRUE on success and FALSE on failure, other functions may have different ways of indicating success/failure. Also note that the err variable is initialized to NULL; this is required.

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:

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.

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.

#include <gconf/gconf.h>
void gconf_error_new (GConfError en, const gchar* format, ...);