The GConfValue Datatype

The GConfValue struct represents a value that can be obtained from or stored in the configuration database. It is simply a type marker and a union of several value types, with constructor, destructor, "setter" and "getter" functions. When possible the GConf library allows you to deal with simple C types instead of a GConfValue, but sometimes there is simply no way to know the type of an object in advance. The libgnome/gnome-config.h interface simply returns strings in this case, for the programmer to parse manually; this was phenomenally broken and GConf fixes it with GConfValue.

Accessing GConfValue

To read a GConfValue, you first determine its type and then read the value using one of its accessor macros. The following useless code should demonstrate this:

            
void
print_value(GConfValue* value)
{    
  switch (value->type)
    {
    case GCONF_VALUE_STRING:
      printf("%s\n", gconf_value_get_string(value));
      break;
    case GCONF_VALUE_INT:
      printf("%d\n", gconf_value_get_int(value));
      break;
    case GCONF_VALUE_FLOAT:
      printf("%g\n", gconf_value_get_float(value));
      break;
    case GCONF_VALUE_BOOL:
      printf("%s", gconf_value_get_bool(value) ? "true" : "false");
      break;
    case GCONF_VALUE_SCHEMA:
      {
        GConfSchema* schema = gconf_value_get_schema(value);

        /* printing a schema would be complicated, you get the idea */
      }
      break;
    case GCONF_VALUE_LIST:
      {
        GSList* iter = gconf_value_get_list(value);

        while (iter != NULL)
          {
            GConfValue* element = iter->data;
            
            print_value(element);
            
            iter = g_slist_next(iter);
          }
      }
      break;
    case GCONF_VALUE_PAIR:
      print_value(gconf_value_get_car(value));
      print_value(gconf_value_get_cdr(value));
      break;
    case GCONF_VALUE_INVALID:
      /* This is used internally by GConf, you can also
         use it yourself to indicate errors and such. It
         won't be returned from GConf functions though. */
      printf("invalid value");
      break;
      
    default:
      g_assert_not_reached();
      break;
    }
}

A special note about values of type GCONF_VALUE_LIST: the list contains GConfValue objects, and all objects in the list must have the same type. You can get the type of the list with the gconf_value_get_list_type() macro.

Creating/destroying a GConfValue

Often you obtain a GConfValue from a GConf routine such as gconf_engine_get (), but you can also create them yourself with gconf_value_new(). gconf_value_new() takes a single argument, the type of the newly-created value. Value types can't be changed after creating the value.

#include <gconf/gconf-value.h>

<funcdef>GConfValue* gconf_value_new </funcdef><paramdef>GConfValueType type</paramdef>

Note that gconf/gconf-value.h is automatically included by gconf/gconf.h.

You must initialize your values

Newly-constructed values are invalid; if you use the accessor macros before you set the contents of the value, the results are undefined. Use gconf_value_set_int(), gconf_value_set_string(), and so on to initialize the value.

You can destroy a GConfValue with gconf_value_free(), and copy one with gconf_value_copy(). The copy is a deep copy, that is, child values contained in lists or pairs are also copied.

#include <gconf/gconf-value.h>

<funcdef>GConfValue* gconf_value_copy </funcdef><paramdef>GConfValue* src</paramdef><funcdef>void gconf_value_free </funcdef><paramdef>GConfValue* value</paramdef>