Gnome Developers' Information
<<< Previous |  | Next >>>

# GNOME library.

This chapter is intended to be a reference to the libgnome.

# gnome-config

## Author(s)

Miguel de Icaza <miguel@nuclecu.unam.mx>

## Description

A set of routines for manipulating the database of configuration information.

## Glossary

- "config path" - a string that specifies which item to retrieve from the configuration database. For example, a config path of "/myapp/display_toolbox" could be used to retrieve the setting for whether 'myapp' should display its toolbox.

- "default" - when retrieving a config item, specifies the value to be used if the item is not found.

- "private configuration data" - Normally, config item data is located in files under the ~user/.gnome directory in a .ini-like format. These files are world-readable. Items that have security or privacy implications are stored and retrieved using the "private" versions of the gnome-config routines, and the data for these items is stored in files under the ~user/.gnome_private directory, which is not accessable by anyone except that user and the system administrator.

- "translated" strings - GNOME's multilingual support means that multiple languages must be supported for configuration items. The gnome_config_*get_translated_string() and gnome_config_*set_translated_string() routines allow you to specify which language a string item should be accessed for.

- "section" - a group of config items and other config sections

## gnome_config_*get_* - routines to retrieve information for a specified config path.

`type `gnome_config_get_typename``(const char *`path`);

### Description

Routine to retrieve a config item. 'typename' would be one of string, translated_string, int, bool, float, or vector. In the case of the gnome_config_get_string(), gnome_config_get_translated_string(), and gnome_config_get_vector(), ownership of the memory used by the returned value is given over to the application. When the application is done with it, it should be freed using g_free() or g_string_array_free() as appropriate.

Combinations of "private" and "with_default" versions of these routines exist. For example, there are gnome_config_get_string(), gnome_config_get_string_with_default() gnome_config_private_get_string(), and gnome_config_private_get_string_with_default() routines.

### Usage

    char *myitem;
    gboolean is_default;

    myitem =
    gnome_config_get_string_with_default("/foo/blah=DefaultValue", &is_default);

### Parameters

- const char *`path`

  The config path to the config item being accessed.

- gboolean *`def` (gnome_config_get_*_with_default() routines only)

  Address of a gboolean variable. Used to return an indication to the caller as to whether the return value is a default value or was retrieved from the config database for the specified 'path'.

## gnome_config_set_* - routines to store information for a specified config path.

`void `gnome_config_set_typename``(const char *`path`, type `value`);

### Description>

Stores the specified value into the configuration database at the specified config path.

Note that there are "private" variations on all the regular routines, e.g. gnome_config_set_string() and gnome_config_private_set_string().

### Usage

    char *values[] = {"A one", "a two", "a three"};

    gnome_config_set_vector("/foo/bar/baz", 3, values);

## gnome_config_has_section - Checks whether a config section exists

`gboolean `gnome_config_has_section``(const char *`path`);

### Description

This routine returns TRUE if the specified section/item exists, xor FALSE if it does not.

A parallel gnome_config_private_has_section() routine also is available.

### Usage

    if(gnome_config_has_section("/foo/bar/baz")) {
            g_print("You have saved preferences.\n");
    } else {
            g_print("You haven't saved preferences yet.\n");
    }

### Parameters

- const char *`path`

  Config path of the item/section of interest

## gnome_config_init_iterator - Setup an iterator to get a listing of items in a specified config section.

`void *`gnome_config_init_iterator``(const char *`path`);

### Description

This routine is used to begin a loop over all the items in a config section. gnome_config_iterator_next() is used to advance to the next item.

Note that a gnome_config_private_init_iterator() variant exists.

### Usage

See the gnome_config_iterator_next() usage example

### Parameters

- const char *`path`

  Config section to list the items in.

## gnome_config_init_iterator - Setup an iterator to get a listing of sections in a specified config section.

`void *`gnome_config_init_iterator_sections``(const char *`path`);

### Description

This routine is used to begin a loop over all the items in a config section. gnome_config_iterator_next() is used to advance to the next item.

Note that a gnome_config_private_init_iterator_sections() variant exists.

### Usage

See the gnome_config_iterator_next() usage example

### Parameters

- const char *`path`

  Config section to list the sub-sections of.

## gnome_config_iterator_next - get the next item from an iterator

`void *`gnome_config_iterator_next``(void *`s`, char **`key`, char **`value`);

### Description

This function normally serves as the loop update for a config item or section iterator. The return value is an opaque pointer needed by gnome_config_iterator_next, or NULL if there are no more available data in the iterator.

### Usage

    char *section_name, *key, *value;
    void *section_iter, *item_iter;
    GString *tmpstr;
    tmpstr = g_string_new(NULL);
    for(section_iter = gnome_config_init_iterator_sections("/foo");
        section_iter != NULL;
        section_iter = gnome_config_iterator_next(section_iter, NULL, &section_name)) {

        g_string_sprintf(tmpstr, "/foo/%s", section_name);

        for(item_iter = gnome_config_init_iterator(tmpstr->str);
            item_iter;
            item_iter = gnome_config_iterator_next(item_iter, &key, &value)) {
            g_print("Got key %s -> value %s in section %s of /foo\n",
                    key, value, section_name);

            g_free(key); g_free(value);
        }

        g_free(section_name);
    }
    g_string_free(tmpstr);

### Parameters

- void *`s`

  A value returned by either gnome_config_*_init_iterator_*() or gnome_config_iterator_next().

- char **`key`

  The address of a char * variable. Used to return a pointer to the key for item iterators. For section iterators, this should be NULL.

- char **`value`

  The address of a char * variable. Used to return a pointer to the value for item iterators, or to the section name for section iterators.

## gnome_config_drop_all - drops all the cached config data from the in-memory cache

`void `gnome_config_drop_all``(void);

### Description

The gnome_config routines cache the configuration entries in memory to increase speed. Calling gnome_config_drop_all() causes the cache to be cleared.

## gnome_config_sync - writes all unwritten config entries to the config database

`void `gnome_config_sync``(void);

### Description

As previously stated, the gnome_config routines cache configuration entries in memory to increase speed. This routine flushes the cache to disk - you would ordinarily use it after a number of gnome_config_set_* operations.

## gnome_config_*clean_* - routines for removing a configuration database entry or subtree altogether

`void `gnome_config_clean_file``(const char *`path`);

`void `gnome_config_private_clean_file``(const char *`path`);

`void `gnome_config_clean_section``(const char *`path`);

`void `gnome_config_private_clean_section``(const char *`path`);

`void `gnome_config_clean_key``(const char *`path`);

`void `gnome_config_private_clean_key``(const char *`path`);

### Description

These routines delete all the configuration entries associated with the specified entity (either a file, section, or key).

### Usage

    char *val1, *val2;

    gnome_config_set_string("/foo/bar", "baz");
    val1 = gnome_config_get_string("/foo/bar");
    gnome_config_clean_section("/foo");
    val2 = gnome_config_get_string("/foo/bar");
    if(val1 && val2 && !strcmp(val1, val2)) {
        g_error("The values match! gnome_config_clean_section is broken!");
    } else {
        g_message("gnome_config_clean_section worked.");
    }

### Parameters

- const char *`path`

  The config path to the config item which is to be removed.

## gnome_config_*get_real_path

`char *`gnome_config_get_real_path``(const char *`path`);

`char *`gnome_config_private_get_real_path``(const char *`path`);

### Description

Occasionally an application writer may want to get the local filename where a config item is stored. When passed a config path, these routines (currently implemented as macros) return that filename.

### Usage

    char *filename = gnome_config_get_real_path("/foo/bar");
    FILE *filehandle = fopen(filename, "w");
    /* do devious things with the file */

### Parameters

- const char *`path`

  The config path to the config item being accessed.

<<< Previous | Home | Next >>>
Architecture notes. |  | gnome-defs