gnome-config routines provide a simple way of retrieving and storing configuration values (the routines provide handling of default values to simplify the code).
config path: a string that specifies which item to retrieve from the configuration database. The config path is composed of three elements: the first one is the filename where the information is stored, the second component is the section and the third one is the key inside the section
For example, a config path of "/myapp/toolbox/showit" could be used to retrieve the setting for whether 'myapp' should display its toolbox or not. In this example "myapp" is the file name (which is stored in ~/.gnome directory), "toolbox" is the section and "showit" is the key.
If you want to access an absolute file instead of a ~/.gnome-relative file, then you need to surround the filename with equal signs, for example, to access the key "mykey" from the section "mysection" in a configuration file located in /gnome/var/myconfig you need to use this path: "=/gnome/var/myconfig=/mysection/mykey".
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_*
"section" - a group of config items and other config sections
There are two types of routines
FIXME: Finish this. Explain the different types of routines, explain the _private versions, explain the vector use, etc
#define gnome_config_get_string_with_default(path,def) |
Retrieves & returns the value of a configuration item as a string.
The returned value should be
#define gnome_config_get_translated_string_with_default(path,def) |
Retrieves & returns the value of a configuration item as a string appropriate for the current language. The returned value should be
#define gnome_config_get_int_with_default(path,def) |
Retrieves & returns the value of a configuration item as an integer.
#define gnome_config_get_float_with_default(path,def) |
Retrieves & returns the value of a configuration item as a floating-point number.
#define gnome_config_get_bool_with_default(path,def) |
Retrieves & returns the value of a configuration item as a boolean.
#define gnome_config_get_vector_with_default(path, argcp, argvp, def) |
Retrieves & returns the value of a configuration item as a string array.
The returned value should be
#define gnome_config_private_get_string_with_default(path,def) |
Retrieves & returns the value of a configuration item as a string.
The returned value should be
#define gnome_config_private_get_translated_string_with_default(path,def) |
Retrieves & returns the value of a configuration item as a string appropriate for the current language. The returned value should be
#define gnome_config_private_get_int_with_default(path,def) |
Retrieves & returns the value of a configuration item as an integer. The item is retrieved from the user's private configuration storage area.
#define gnome_config_private_get_float_with_default(path,def) |
Retrieves & returns the value of a configuration item as a floating-point number. The item is retrieved from the user's private configuration storage area.
#define gnome_config_private_get_bool_with_default(path,def) |
Retrieves & returns the value of a configuration item as a boolean. The item is retrieved from the user's private configuration storage area.
#define gnome_config_private_get_vector_with_default(path, argcp, argvp, def) |
Retrieves & returns the value of a configuration item as a string array.
The returned value should be
#define gnome_config_get_string(path) |
Retrieves & returns the value of a configuration item as a string.
The returned value should be
#define gnome_config_get_translated_string(path) |
Retrieves & returns the value of a configuration item as a string
appropriate for the current language. The returned value should be
#define gnome_config_get_int(path) |
Retrieves & returns the value of a configuration item as an integer.
#define gnome_config_get_float(path) |
Retrieves & returns the value of a configuration item as a floating-point number.
#define gnome_config_get_bool(path) |
Retrieves & returns the value of a configuration item as a boolean.
#define gnome_config_get_vector(path, argcp, argvp) |
Retrieves & returns the value of a configuration item as a string array.
The returned value should be
#define gnome_config_private_get_string(path) |
Retrieves & returns the value of a configuration item as a
string. The returned value should be
#define gnome_config_private_get_translated_string(path) |
Retrieves & returns the value of a configuration item as a string appropriate for the current language. The returned value should be
#define gnome_config_private_get_int(path) |
Retrieves & returns the value of a configuration item as an integer. The item is retrieved from the user's private configuration storage area.
#define gnome_config_private_get_float(path) |
Retrieves & returns the value of a configuration item as a floating-point number. The item is retrieved from the user's private configuration storage area.
#define gnome_config_private_get_bool(path) |
Retrieves & returns the value of a configuration item as a boolean. The item is retrieved from the user's private configuration storage area.
#define gnome_config_private_get_vector(path, argcp, argvp) |
Retrieves & returns the value of a configuration item as a
string. The returned value should be
#define gnome_config_set_string(path,new_value) |
Stores the string value new_value in the file/section/key defined by the path
#define gnome_config_set_translated_string(path,value) |
Stores the string value new_value in the file/section/key defined by the path on the proper section for the current language set by by the user.
#define gnome_config_set_int(path,new_value) |
Stores the integer value new_value in the file/section/key defined by the path
#define gnome_config_set_float(path,new_value) |
Stores the double value new_value in the file/section/key defined by the path
#define gnome_config_set_bool(path,new_value) |
Stores boolean value new_value in the file/section/key defined by path.
#define gnome_config_set_vector(path,argc,argv) |
Stores vector argv in the file/section/key defined by path.
#define gnome_config_private_set_string(path,val) |
#define gnome_config_private_set_translated_string(path,val) |
#define gnome_config_private_set_float(path,value) |
#define gnome_config_private_set_vector(path,argc,argv) |
#define gnome_config_has_section(path) |
Queries the gnome configuration file for the presence of the section specified in path.
#define gnome_config_private_has_section(Path) |
Queries the private gnome configuration file for the presence of the section specified in path.
#define gnome_config_init_iterator(path) |
Creates an iterator handle that can be used to iterate over the keys in a section in a gnome configuration file. path must refer to a section. The returned value can be used as an iterator for gnome_config_iterator_next().
#define gnome_config_private_init_iterator(path) |
Creates an iterator handle that can be used to iterate over the keys in a section in a private gnome configuration file. path must refer to a section. The returned value can be used as an iterator for gnome_config_iterator_next().
#define gnome_config_init_iterator_sections(path) |
Creates an iterator handle that can be used to iterate over the sections in a gnome configuration file. path must refer to a gnome configuration file. The returned value can be used as an iterator for gnome_config_iterator_next().
#define gnome_config_private_init_iterator_sections(path) |
Creates an iterator handle that can be used to iterate over the sections in a private gnome configuration file. path must refer to a gnome configuration file. The returned value can be used as an iterator for gnome_config_iterator_next().
void* gnome_config_iterator_next (void *iterator_handle, char **key, char **value); |
void gnome_config_drop_all (void); |
Drops any information cached in memory that was fetched with gnome config. Any pending information that has not been written to disk is discarded.
void gnome_config_sync (void); |
Writes all of the information modified by gnome-config to the disk.
Note: the gnome_config code does not write anything to the configuration files until this routine is actually invoked.
#define gnome_config_sync_file(path) |
Writes all of the information modified by gnome-config to the disk for the given file.
Note: the gnome_config code does not write anything to the configuration files until this routine or gnome_config_sync is actually invoked.
#define gnome_config_private_sync_file(path) |
Writes all of the information modified by gnome-config to the disk for the given private file.
Note: the gnome_config code does not write anything to the configuration files until this routine or gnome_config_sync is actually invoked.
#define gnome_config_drop_file(path) |
Releases any memory resources that were allocated from accessing the configuration file in path. Changes will take place after gnome_config_sync has been invoked
#define gnome_config_private_drop_file(path) |
Releases any memory resources that were allocated from accessing the private configuration file in path.
#define gnome_config_clean_file(path) |
Cleans up the configuration file specified by path from any configuration information.
Changes will take place after gnome_config_sync has been invoked.
#define gnome_config_private_clean_file(path) |
Cleans up the private configuration file specified by path from any configuration information.
Changes will take place after gnome_config_sync has been invoked.
#define gnome_config_clean_section(path) |
Cleans up the section specified by path from any configuration information. Changes will only take place after gnome_config has been invoked.
#define gnome_config_private_clean_section(Path) |
Cleans up the section specified by path in a private file from any configuration information. Changes will only take place after gnome_config has been invoked.
#define gnome_config_clean_key(path) |
Removes the definition for the key on a gnome configuration file.
Changes will take place after gnome_config_sync has been invoked.
#define gnome_config_private_clean_key(path) |
Removes the definition for the key on a private gnome configuration file.
Changes will take place after gnome_config_sync has been invoked.
void gnome_config_push_prefix (const char *path); |
path is a prefix that will be prepended automatically to any non-absolute configuration path in gnome config.
This is used to simplify application loading code.
Library code will usually have to set the prefix before doing any gnome-configuration access, since the application might be using their own prefix.
void gnome_config_pop_prefix (void); |
Call this routine to remove the current configuration prefix from the stack.
void gnome_config_make_vector (const char *string, int *argcp, char ***argvp); |
char* gnome_config_assemble_vector (int argc, const char *const argv[]); |
This routine returns the the strings in the array contactenated by spaces.
void gnome_config_set_set_handler (void (*func) (void *), void *data); |
Internal Obsolete.