| Gnome Developers' Information | ||
|---|---|---|
| <<< Previous | Next >>> | |
This chapter is intended to be a reference to the libgnome.
Miguel de Icaza <miguel@nuclecu.unam.mx>
A set of routines for manipulating the database of configuration information.
"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
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.
char *myitem;
gboolean is_default;
myitem =
gnome_config_get_string_with_default("/foo/blah=DefaultValue", &is_default); |
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'.
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().
char *values[] = {"A one", "a two", "a three"};
gnome_config_set_vector("/foo/bar/baz", 3, values); |
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.
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");
} |
const char *path
Config path of the item/section of interest
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.
See the gnome_config_iterator_next() usage example
const char *path
Config section to list the items in.
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.
See the gnome_config_iterator_next() usage example
const char *path
Config section to list the sub-sections of.
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.
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, §ion_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); |
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.
The gnome_config routines cache the configuration entries in memory to increase speed. Calling gnome_config_drop_all() causes the cache to be cleared.
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.
These routines delete all the configuration entries associated with the specified entity (either a file, section, or key).
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.");
} |
const char *path
The config path to the config item which is to be removed.
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.
char *filename = gnome_config_get_real_path("/foo/bar");
FILE *filehandle = fopen(filename, "w");
/* do devious things with the file */ |
const char *path
The config path to the config item being accessed.
| <<< Previous | Home | Next >>> |
| Architecture notes. | gnome-defs |