# 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>

`GConfValue* gconf_value_new` (GConfValueType type);

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>

`GConfValue* gconf_value_copy` (GConfValue* src);`void gconf_value_free` GConfValue* value);