Gnome Library Reference Manual
<<< Previous PageHomeUpNext Page >>>

gnome-config

Name

gnome-config -- Simple access to configuration values (50% done)

Synopsis


#include <gnome.h>


#define     gnome_config_get_string_with_default(path,def)
#define     gnome_config_get_translated_string_with_default(path,def)
#define     gnome_config_get_int_with_default(path,def)
#define     gnome_config_get_float_with_default(path,def)
#define     gnome_config_get_bool_with_default(path,def)
#define     gnome_config_get_vector_with_default(path, argcp, argvp, def)
#define     gnome_config_private_get_string_with_default(path,def)
#define     gnome_config_private_get_translated_string_with_default(path,def)
#define     gnome_config_private_get_int_with_default(path,def)
#define     gnome_config_private_get_float_with_default(path,def)
#define     gnome_config_private_get_bool_with_default(path,def)
#define     gnome_config_private_get_vector_with_default(path, argcp, argvp, def)
#define     gnome_config_get_string         (path)
#define     gnome_config_get_translated_string(path)
#define     gnome_config_get_int            (path)
#define     gnome_config_get_float          (path)
#define     gnome_config_get_bool           (path)
#define     gnome_config_get_vector         (path, argcp, argvp)
#define     gnome_config_private_get_string (path)
#define     gnome_config_private_get_translated_string(path)
#define     gnome_config_private_get_int    (path)
#define     gnome_config_private_get_float  (path)
#define     gnome_config_private_get_bool   (path)
#define     gnome_config_private_get_vector (path, argcp, argvp)
#define     gnome_config_set_string         (path,new_value)
#define     gnome_config_set_translated_string(path,value)
#define     gnome_config_set_int            (path,new_value)
#define     gnome_config_set_float          (path,new_value)
#define     gnome_config_set_bool           (path,new_value)
#define     gnome_config_set_vector         (path,argc,argv)
#define     gnome_config_private_set_string (path,new_value)
#define     gnome_config_private_set_translated_string(path,new_value)
#define     gnome_config_private_set_int    (path,new_value)
#define     gnome_config_private_set_float  (path,new_value)
#define     gnome_config_private_set_bool   (path,new_value)
#define     gnome_config_private_set_vector (path,argc,argv)
#define     gnome_config_has_section        (path)
#define     gnome_config_private_has_section(path)
#define     gnome_config_init_iterator      (path)
#define     gnome_config_private_init_iterator(path)
#define     gnome_config_init_iterator_sections(path)
#define     gnome_config_private_init_iterator_sections(path)
void*       gnome_config_iterator_next      (void *iterator_handle,
                                             char **key,
                                             char **value);
void        gnome_config_drop_all           (void);
void        gnome_config_sync               (void);
#define     gnome_config_sync_file          (path)
#define     gnome_config_private_sync_file  (path)
#define     gnome_config_drop_file          (path)
#define     gnome_config_private_drop_file  (path)
#define     gnome_config_clean_file         (path)
#define     gnome_config_private_clean_file (path)
#define     gnome_config_clean_section      (path)
#define     gnome_config_private_clean_section(path)
#define     gnome_config_clean_key          (path)
#define     gnome_config_private_clean_key  (path)
#define     gnome_config_get_real_path      (path)
#define     gnome_config_private_get_real_path(path)
void        gnome_config_push_prefix        (const char *path);
void        gnome_config_pop_prefix         (void);
void        gnome_config_make_vector        (const char *string,
                                             int *argcp,
                                             char ***argvp);
char*       gnome_config_assemble_vector    (int argc,
                                             const char *const argv[]);
void        gnome_config_set_set_handler    (void (*func) (void *),
                                             void *data);
void        gnome_config_set_sync_handler   (void (*func) (void *),
                                             void *data);

Description

gnome-config routines provide a simple way of retrieving and storing configuration values (the routines provide handling of default values to simplify the code).

Definitions.

How Config Items are Read.

GNOME has a versatile method of storing config items. When a config item is written by a program, it is written to a file under the ~/.gnome hierarchy. However, when config items are read, the process is a little more complicated. There are a number of places that are searched. If the config item is not found in one, then the next place is checked, finally falling back to the default value provided by the application. The locations are as follows:

Possible uses for this are setting system wide defaults such as proxy servers for the system (either using config-override to enforce such a policy or the config directory to suggest such a default). It is also possible to configure the application through its graphical interface, and then copy the configuration file accross to the appropriate system-wide directory. The config-override directory should be used sparingly, as it could annoy or confuse some users. Note also that some applications will not read the config items every time they are needed, so putting defaults into the config-override directory will not always completely enforce a setting.

There are two types of routines

FIXME: Finish this. Explain the different types of routines, explain the _private versions, explain the vector use, etc

Details

gnome_config_get_string_with_default()

#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 g_free()'d when no longer needed.

path : A gnome configuration path to an item.
def : A pointer to a flag that will be set if the default value for the item is returned.

gnome_config_get_translated_string_with_default()

#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 g_free()'d when no longer needed.

path : A gnome configuration path to an item.
def : A pointer to a flag that will be set if the default value for the item is returned.

gnome_config_get_int_with_default()

#define     gnome_config_get_int_with_default(path,def)

Retrieves & returns the value of a configuration item as an integer.

path : A gnome configuration path to an item.
def : A pointer to a flag that will be set if the default value for the item is returned.

gnome_config_get_float_with_default()

#define     gnome_config_get_float_with_default(path,def)

Retrieves & returns the value of a configuration item as a floating-point number.

path : A gnome configuration path to an item.
def : A pointer to a flag that will be set if the default value for the item is returned.

gnome_config_get_bool_with_default()

#define     gnome_config_get_bool_with_default(path,def)

Retrieves & returns the value of a configuration item as a boolean.

path : A gnome configuration path to an item.
def : A pointer to a flag that will be set if the default value for the item is returned.

gnome_config_get_vector_with_default()

#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 g_free()'d when no longer needed.

path : A gnome configuration path to an item.
argcp : Number of elements in the vector
argvp : Vector of strings
def : A pointer to a flag that will be set if the default value for the item is returned.

gnome_config_private_get_string_with_default()

#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 g_free()'d when no longer needed. The item is retrieved from the user's private configuration storage area.

path : A gnome configuration path to an item in the user-private namespace.
def : A pointer to a flag that will be set if the default value for the item is returned.

gnome_config_private_get_translated_string_with_default()

#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 g_free()'d when no longer needed. The item is retrieved from the user's private configuration storage area.

path : A gnome configuration path to an item in the user-private namespace.
def : A pointer to a flag that will be set if the default value for the item is returned.

gnome_config_private_get_int_with_default()

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

path : A gnome configuration path to an item in the user-private namespace.
def : A pointer to a flag that will be set if the default value for the item is returned.

gnome_config_private_get_float_with_default()

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

path : A gnome configuration path to an item in the user-private namespace.
def : A pointer to a flag that will be set if the default value for the item is returned.

gnome_config_private_get_bool_with_default()

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

path : A gnome configuration path to an item in the user-private namespace.
def : A pointer to a flag that will be set if the default value for the item is returned.

gnome_config_private_get_vector_with_default()

#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 g_free()'d when no longer needed. The item is retrieved from the user's private configuration storage area.

path : A gnome configuration path to an item in the user-private namespace.
argcp : Number of elements in the vector
argvp : Vector of strings
def : A pointer to a flag that will be set if the default value for the item is returned.

gnome_config_get_string()

#define     gnome_config_get_string(path)

Retrieves & returns the value of a configuration item as a string. The returned value should be g_free()'d when no longer needed.

path : A gnome configuration path to an item.

gnome_config_get_translated_string()

#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 g_free()'d when no longer needed.

path : A gnome configuration path to an item.

gnome_config_get_int()

#define     gnome_config_get_int(path)

Retrieves & returns the value of a configuration item as an integer.

path : A gnome configuration path to an item.

gnome_config_get_float()

#define     gnome_config_get_float(path)

Retrieves & returns the value of a configuration item as a floating-point number.

path : A gnome configuration path to an item.

gnome_config_get_bool()

#define     gnome_config_get_bool(path)

Retrieves & returns the value of a configuration item as a boolean.

path : A gnome configuration path to an item.

gnome_config_get_vector()

#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 g_free()'d when no longer needed.

path : A gnome configuration path to an item.
argcp : Number of elements in the vector
argvp : Vector of strings

gnome_config_private_get_string()

#define     gnome_config_private_get_string(path)

Retrieves & returns the value of a configuration item as a string. The returned value should be g_free()'d when no longer needed. The item is retrieved from the user's private configuration storage area.

path : A gnome configuration path to an item in the user-private namespace.

gnome_config_private_get_translated_string()

#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 g_free()'d when no longer needed. The item is retrieved from the user's private configuration storage area.

path : A gnome configuration path to an item in the user-private namespace.

gnome_config_private_get_int()

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

path : A gnome configuration path to an item in the user-private namespace.

gnome_config_private_get_float()

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

path : A gnome configuration path to an item in the user-private namespace.

gnome_config_private_get_bool()

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

path : A gnome configuration path to an item in the user-private namespace.

gnome_config_private_get_vector()

#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 g_free()'d when no longer needed. The item is retrieved from the user's private configuration storage area.

path : A gnome configuration path to an item in the user-private namespace.
argcp : Number of elements in the vector
argvp : Vector of strings

gnome_config_set_string()

#define     gnome_config_set_string(path,new_value)

Stores the string value new_value in the file/section/key defined by the path

path : a gnome configuration path to a key
new_value : a string value to set.

gnome_config_set_translated_string()

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

path : a gnome configuration path to a key
value : a string value to set.

gnome_config_set_int()

#define     gnome_config_set_int(path,new_value)

Stores the integer value new_value in the file/section/key defined by the path

path : a gnome configuration path to a key
new_value : a int value to set.

gnome_config_set_float()

#define     gnome_config_set_float(path,new_value)

Stores the double value new_value in the file/section/key defined by the path

path : a gnome configuration path to a key
new_value : a double value to set.

gnome_config_set_bool()

#define     gnome_config_set_bool(path,new_value)

Stores boolean value new_value in the file/section/key defined by path.

path : a gnome configuration path to a key
new_value : a boolean value to set

gnome_config_set_vector()

#define     gnome_config_set_vector(path,argc,argv)

Stores vector argv in the file/section/key defined by path.

path : a gnome configuration path to a key
argc : the number of elements in argv
argv : a string array holding the data to store.

gnome_config_private_set_string()

#define     gnome_config_private_set_string(path,new_value)

path : 
new_value : 

gnome_config_private_set_translated_string()

#define     gnome_config_private_set_translated_string(path,new_value)

path : 
new_value : 

gnome_config_private_set_int()

#define     gnome_config_private_set_int(path,new_value)

path : 
new_value : 

gnome_config_private_set_float()

#define     gnome_config_private_set_float(path,new_value)

path : 
new_value : 

gnome_config_private_set_bool()

#define     gnome_config_private_set_bool(path,new_value)

path : 
new_value : 

gnome_config_private_set_vector()

#define     gnome_config_private_set_vector(path,argc,argv)

path : 
argc : 
argv : 

gnome_config_has_section()

#define     gnome_config_has_section(path)

Queries the gnome configuration file for the presence of the section specified in path.

path : A gnome configuration path to a section

gnome_config_private_has_section()

#define     gnome_config_private_has_section(path)

Queries the private gnome configuration file for the presence of the section specified in path.

path : A gnome configuration path to a section

gnome_config_init_iterator()

#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().

path : A gnome configuration path for a section.

gnome_config_private_init_iterator()

#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().

path : A gnome configuration path for a section.

gnome_config_init_iterator_sections()

#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().

path : A gnome configuration path for a file.

gnome_config_private_init_iterator_sections()

#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().

path : A gnome configuration path for a file

gnome_config_iterator_next ()

void*       gnome_config_iterator_next      (void *iterator_handle,
                                             char **key,
                                             char **value);

iterator_handle : A gnome configu iterator handle, returned from any iteration start routine or this routine.
key : Address where the key gets stored.
value : Address where the value gets stored.

gnome_config_drop_all ()

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.

gnome_config_sync ()

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.

gnome_config_sync_file()

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

path : A gnome-config path

gnome_config_private_sync_file()

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

path : A gnome-config path

gnome_config_drop_file()

#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

path : A gnome-config path

gnome_config_private_drop_file()

#define     gnome_config_private_drop_file(path)

Releases any memory resources that were allocated from accessing the private configuration file in path.

path : A gnome-config path

gnome_config_clean_file()

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

path : A gnome-config path

gnome_config_private_clean_file()

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

path : A gnome-config path

gnome_config_clean_section()

#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_sync has been invoked.

path : a gnome configuration path to a section.

gnome_config_private_clean_section()

#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_sync has been invoked.

path : a gnome configuration path to a section.

gnome_config_clean_key()

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

path : a gnome configuration path to a key.

gnome_config_private_clean_key()

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

path : a gnome configuration path to a key.

gnome_config_get_real_path()

#define     gnome_config_get_real_path(path)

path : 

gnome_config_private_get_real_path()

#define     gnome_config_private_get_real_path(path)

path : 

gnome_config_push_prefix ()

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.

path : a gnome configuration path prefix

gnome_config_pop_prefix ()

void        gnome_config_pop_prefix         (void);

Call this routine to remove the current configuration prefix from the stack.

gnome_config_make_vector ()

void        gnome_config_make_vector        (const char *string,
                                             int *argcp,
                                             char ***argvp);

Creates a new vector from a string as it stored in the config file, breaks the string on spaces except if the space is escaped with a backslash.

string : The stringified vector to decode into 'argcp' and 'argvp'
argcp : Returns the number of elements in 'argvp'
argvp : Returns the array of strings found in 'rr'.

gnome_config_assemble_vector ()

char*       gnome_config_assemble_vector    (int argc,
                                             const char *const argv[]);

This routine returns the the strings in the array contactenated by spaces.

argc : Number of elements in the argv string array.
argv : An array of strings.
Returns : a g_malloc()ed string with the concatenation results.

gnome_config_set_set_handler ()

void        gnome_config_set_set_handler    (void (*func) (void *),
                                             void *data);

Internal Obsolete.

func : Obsolete
data : Obsolete

gnome_config_set_sync_handler ()

void        gnome_config_set_sync_handler   (void (*func) (void *),
                                             void *data);

Internal routine

func : obsolete
data : obsolete



<<< Previous PageHomeUpNext Page >>>
Gnome Librarygnome-defs