## Configuration

Configuration — Access/Management of libgda configuration

## Synopsis

    void                (*GdaConfigListenerFunc)            (const gchar *path,
                                                             gpointer user_data);
                        GdaProviderInfo;
                        GdaDataSourceInfo;
    gchar*              gda_config_get_string               (const gchar *path);
    gint                gda_config_get_int                  (const gchar *path);
    gdouble             gda_config_get_float                (const gchar *path);
    gboolean            gda_config_get_boolean              (const gchar *path);
    gboolean            gda_config_set_string               (const gchar *path,
                                                             const gchar *new_value);
    gboolean            gda_config_set_int                  (const gchar *path,
                                                             gint new_value);
    gboolean            gda_config_set_float                (const gchar *path,
                                                             gdouble new_value);
    gboolean            gda_config_set_boolean              (const gchar *path,
                                                             gboolean new_value);
    void                gda_config_remove_section           (const gchar *path);
    void                gda_config_remove_key               (const gchar *path);
    gboolean            gda_config_has_section              (const gchar *path);
    gboolean            gda_config_has_key                  (const gchar *path);
    GList*              gda_config_list_sections            (const gchar *path);
    GList*              gda_config_list_keys                (const gchar *path);
    void                gda_config_free_list                (GList *list);
    GList*              gda_config_get_provider_list        (void);
    void                gda_config_free_provider_list       (GList *list);
    GdaProviderInfo*    gda_config_get_provider_by_name     (const gchar *name);
    GdaDataModel*       gda_config_get_provider_model       (void);

    GdaProviderInfo*    gda_provider_info_copy              (GdaProviderInfo *src);
    void                gda_provider_info_free              (GdaProviderInfo *provider_info);
    GList*              gda_config_get_data_source_list     (void);
    GdaDataSourceInfo*  gda_config_find_data_source         (const gchar *name);
    GdaDataSourceInfo*  gda_data_source_info_copy           (GdaDataSourceInfo *src);
    gboolean            gda_data_source_info_equal          (GdaDataSourceInfo *info1,
                                                             GdaDataSourceInfo *info2);
    void                gda_data_source_info_free           (GdaDataSourceInfo *info);
    void                gda_config_free_data_source_list    (GList *list);
    GdaDataModel*       gda_config_get_data_source_model    (void);
    gboolean            gda_config_can_modify_global_config (void);
    gboolean            gda_config_save_data_source         (const gchar *name,
                                                             const gchar *provider,
                                                             const gchar *cnc_string,
                                                             const gchar *description,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             gboolean is_global);
    gboolean            gda_config_save_data_source_info    (GdaDataSourceInfo *dsn_info);
    void                gda_config_remove_data_source       (const gchar *name);
    guint               gda_config_add_listener             (const gchar *path,
                                                             GdaConfigListenerFunc func,
                                                             gpointer user_data);
    void                gda_config_remove_listener          (guint id);

## Description

The functions in this section allow applications an easy access to the libgda configuration, thus making them able to access the list of data sources configured in the system, for instance.

## Details

### GdaConfigListenerFunc ()

    void                (*GdaConfigListenerFunc)            (const gchar *path,
                                                             gpointer user_data);

`path` : |
`user_data` : |

### GdaProviderInfo

    typedef struct {
    	gchar            *id;
    	gchar            *location;
    	gchar            *description;
    	GdaParameterList *gda_params; /* Contains a list of GdaParameter to create a DSN */
    	gchar            *dsn_spec; /* XML string with all the parameters required to create a DSN */
    } GdaProviderInfo;

### GdaDataSourceInfo

    typedef struct {
    	gchar    *name;
    	gchar    *provider;
    	gchar    *cnc_string;
    	gchar    *description;
    	gchar    *username;
    	gchar    *password;
    	gboolean  is_global;
    } GdaDataSourceInfo;

### gda_config_get_string ()

    gchar*              gda_config_get_string               (const gchar *path);

Gets the value of the specified configuration entry as a string. You are then responsible to free the returned string.

`path` : | path to the configuration entry.
Returns : | the value stored at the given entry.

### gda_config_get_int ()

    gint                gda_config_get_int                  (const gchar *path);

Gets the value of the specified configuration entry as an integer.

`path` : | path to the configuration entry.
Returns : | the value stored at the given entry.

### gda_config_get_float ()

    gdouble             gda_config_get_float                (const gchar *path);

Gets the value of the specified configuration entry as a float.

`path` : | path to the configuration entry.
Returns : | the value stored at the given entry.

### gda_config_get_boolean ()

    gboolean            gda_config_get_boolean              (const gchar *path);

Gets the value of the specified configuration entry as a boolean.

`path` : | path to the configuration entry.
Returns : | the value stored at the given entry.

### gda_config_set_string ()

    gboolean            gda_config_set_string               (const gchar *path,
                                                             const gchar *new_value);

Sets the given configuration entry to contain a string.

`path` : | path to the configuration entry.
`new_value` : | new value.
Returns : | TRUE if no error occurred

### gda_config_set_int ()

    gboolean            gda_config_set_int                  (const gchar *path,
                                                             gint new_value);

Sets the given configuration entry to contain an integer.

`path` : | path to the configuration entry.
`new_value` : | new value.
Returns : | TRUE if no error occurred

### gda_config_set_float ()

    gboolean            gda_config_set_float                (const gchar *path,
                                                             gdouble new_value);

Sets the given configuration entry to contain a float.

`path` : | path to the configuration entry.
`new_value` : | new value.
Returns : | TRUE if no error occurred

### gda_config_set_boolean ()

    gboolean            gda_config_set_boolean              (const gchar *path,
                                                             gboolean new_value);

Sets the given configuration entry to contain a boolean.

`path` : | path to the configuration entry.
`new_value` : | new value.
Returns : | TRUE if no error occurred

### gda_config_remove_section ()

    void                gda_config_remove_section           (const gchar *path);

Removes the given section from the configuration database.

`path` : | path to the configuration section.

### gda_config_remove_key ()

    void                gda_config_remove_key               (const gchar *path);

Removes the given entry from the configuration database. If the section is empty, also remove the section.

`path` : | path to the configuration entry.

### gda_config_has_section ()

    gboolean            gda_config_has_section              (const gchar *path);

Checks whether the given section exists in the configuration system.

`path` : | path to the configuration section.
Returns : | `TRUE` if the section exists, `FALSE` otherwise.

### gda_config_has_key ()

    gboolean            gda_config_has_key                  (const gchar *path);

Checks whether the given key exists in the configuration system.

`path` : | path to the configuration key.
Returns : | `TRUE` if the entry exists, `FALSE` otherwise.

### gda_config_list_sections ()

    GList*              gda_config_list_sections            (const gchar *path);

Returns a GList containing the names of all the sections available under the given root directory.

To free the returned value, you can use gda_config_free_list.

`path` : | path for root dir.
Returns : | a list containing all the section names.

### gda_config_list_keys ()

    GList*              gda_config_list_keys                (const gchar *path);

Returns a list of all keys that exist under the given path.

To free the returned value, you can use gda_config_free_list.

`path` : | path for root dir.
Returns : | a list containing all the key names.

### gda_config_free_list ()

    void                gda_config_free_list                (GList *list);

Frees all memory used by the given GList, which must be the return value from either gda_config_list_sections and gda_config_list_keys.

`list` : | list to be freed.

### gda_config_get_provider_list ()

    GList*              gda_config_get_provider_list        (void);

Returns a list of all providers currently installed in the system. Each of the nodes in the returned GList is a GdaProviderInfo.

Returns : | a GList of GdaProviderInfo structures, don't free or modify it!

### gda_config_free_provider_list ()

    void                gda_config_free_provider_list       (GList *list);

Frees a list of GdaProviderInfo structures.

`list` : | the list to be freed.

### gda_config_get_provider_by_name ()

    GdaProviderInfo*    gda_config_get_provider_by_name     (const gchar *name);

Gets a GdaProviderInfo structure from the provider list given its name, don't modify or free it.

`name` : | name of the provider to search for.
Returns : | a GdaProviderInfo structure, if found, or `NULL` if not found.

### gda_config_get_provider_model ()

    GdaDataModel*       gda_config_get_provider_model       (void);

Fills and returns a new GdaDataModel object using information from all providers which are currently installed in the system.

Rows are separated in 3 columns: 'Id', 'Location' and 'Description'.

Returns : | a new GdaDataModel object.

### gda_provider_info_copy ()

    GdaProviderInfo*    gda_provider_info_copy              (GdaProviderInfo *src);

Creates a new GdaProviderInfo structure from an existing one.

`src` : | provider information to get a copy from.
Returns : | a newly allocated GdaProviderInfo with contains a copy of information in `src`.

### gda_provider_info_free ()

    void                gda_provider_info_free              (GdaProviderInfo *provider_info);

Deallocates all memory associated to the given GdaProviderInfo.

`provider_info` : | provider information to free.

### gda_config_get_data_source_list ()

    GList*              gda_config_get_data_source_list     (void);

Returns a list of all data sources currently configured in the system. Each of the nodes in the returned GList is a GdaDataSourceInfo. To free the returned list, call the gda_config_free_data_source_list function.

Returns : | a GList of GdaDataSourceInfo structures.

### gda_config_find_data_source ()

    GdaDataSourceInfo*  gda_config_find_data_source         (const gchar *name);

Gets a GdaDataSourceInfo structure from the data source list given its name. After usage, the returned structure's memory must be freed using `gda_data_source_info_free()`.

`name` : | name of the data source to search for.
Returns : | a new GdaDataSourceInfo structure, if found, or `NULL` if not found.

### gda_data_source_info_copy ()

    GdaDataSourceInfo*  gda_data_source_info_copy           (GdaDataSourceInfo *src);

Creates a new GdaDataSourceInfo structure from an existing one.

`src` : | data source information to get a copy from.
Returns : | a newly allocated GdaDataSourceInfo with contains a copy of information in `src`.

### gda_data_source_info_equal ()

    gboolean            gda_data_source_info_equal          (GdaDataSourceInfo *info1,
                                                             GdaDataSourceInfo *info2);

Tells if `info1` and `info2` are equal

`info1` : | a data source information
`info2` : | a data source information
Returns : | TRUE if `info1` and `info2` are equal

### gda_data_source_info_free ()

    void                gda_data_source_info_free           (GdaDataSourceInfo *info);

Deallocates all memory associated to the given GdaDataSourceInfo.

`info` : | data source information to free.

### gda_config_free_data_source_list ()

    void                gda_config_free_data_source_list    (GList *list);

Frees a list of GdaDataSourceInfo structures.

`list` : | the list to be freed.

### gda_config_get_data_source_model ()

    GdaDataModel*       gda_config_get_data_source_model    (void);

Fills and returns a new GdaDataModel object using information from all data sources which are currently configured in the system.

Rows are separated in 6 columns: 'Name', 'Provider', 'Connection string', 'Description', 'Username' and 'Global'.

Returns : | a new GdaDataModel object.

### gda_config_can_modify_global_config ()

    gboolean            gda_config_can_modify_global_config (void);

Tells if the calling program can modify the global configured data sources.

Returns : | TRUE if modifications are possible

### gda_config_save_data_source ()

    gboolean            gda_config_save_data_source         (const gchar *name,
                                                             const gchar *provider,
                                                             const gchar *cnc_string,
                                                             const gchar *description,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             gboolean is_global);

Adds a new data source (or update an existing one) to the GDA configuration, based on the parameters given.

`name` : | name for the data source to be saved.
`provider` : | provider ID for the new data source.
`cnc_string` : | connection string for the new data source.
`description` : | description for the new data source.
`username` : | user name for the new data source.
`password` : | password to use when authenticating `username`.
`is_global` : | TRUE if the data source is system-wide
Returns : | TRUE if no error occurred

### gda_config_save_data_source_info ()

    gboolean            gda_config_save_data_source_info    (GdaDataSourceInfo *dsn_info);

Saves a data source in the libgda configuration given a GdaDataSourceInfo structure containing all the information about the data source.

`dsn_info` : | a GdaDataSourceInfo structure.
Returns : | TRUE if no error occurred

### gda_config_remove_data_source ()

    void                gda_config_remove_data_source       (const gchar *name);

Removes the given data source from the GDA configuration.

`name` : | name for the data source to be removed.

### gda_config_add_listener ()

    guint               gda_config_add_listener             (const gchar *path,
                                                             GdaConfigListenerFunc func,
                                                             gpointer user_data);

Installs a configuration listener, which is a callback function which will be called every time a change occurs on a given configuration entry.

`path` : | configuration path to listen to.
`func` : | callback function.
`user_data` : | data to be passed to the callback function.
Returns : | the ID of the listener, which you will need for calling gda_config_remove_listener. If an error occurs, 0 is returned.

### gda_config_remove_listener ()

    void                gda_config_remove_listener          (guint id);

Removes a configuration listener previously installed with gda_config_add_listener, given its ID.

`id` : | the ID of the listener to remove.