Configuration

## Configuration Configuration — Access/Management of libgda configuration |

## Synopsis

                        GdaConfig;

                        GdaDsnInfo;
    GdaDsnInfo *        gda_config_get_dsn_info             (const gchar *dsn_name);
    gboolean            gda_config_define_dsn               (const GdaDsnInfo *info,
                                                             GError **error);
    gboolean            gda_config_remove_dsn               (const gchar *dsn_name,
                                                             GError **error);
    gboolean            gda_config_dsn_needs_authentication (const gchar *dsn_name);
    GdaDataModel *      gda_config_list_dsn                 (void);
    gint                gda_config_get_nb_dsn               (void);
    gint                gda_config_get_dsn_info_index       (const gchar *dsn_name);
    GdaDsnInfo *        gda_config_get_dsn_info_at_index    (gint index);
    gboolean            gda_config_can_modify_system_config (void);

                        GdaProviderInfo;
    GdaProviderInfo *   gda_config_get_provider_info        (const gchar *provider_name);
    GdaServerProvider * gda_config_get_provider             (const gchar *provider_name,
                                                             GError **error);
    GdaDataModel *      gda_config_list_providers           (void);

    GdaConfig*          gda_config_get                      (void);

## Object Hierarchy

      GObject
       +----GdaConfig

## Properties

      "system-filename"          gchar*                : Read / Write
      "user-filename"            gchar*                : Read / Write

## Signals

      "dsn-added"                                      : Run First
      "dsn-changed"                                    : Run First
      "dsn-removed"                                    : Run First
      "dsn-to-be-removed"                              : Run First

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

As soon as a GdaConfig is needed (for example when requesting information about a data source or about a server provider), a single instance object is created, and no other will need to be created. A pointer to this object can be obtained with `gda_config_get()`. Of course one can (right after having called `gda_init()`) force the creation of a GdaConfig object with some specific properties set, using a simple call like:

    g_object_new (GDA_TYPE_CONFIG, "user-file", "my_file", NULL);

Please note that after that call, the caller has a reference to the newly created object, and should technically call `g_object_unref()` when finished using it. It is safe to do this but also poinless since that object should not be destroyed (as no other will be created) as Libgda also keeps a reference for itself.

Data sources are defined in a per-user configuration file which is by default `${HOME}/.libgda/config` and in a system wide configuration file which is by default `${prefix}/etc/libgda-4.0/config`. Those filenames can be modified by setting the user-file and system-file properties for the single GdaConfig instance. Note that setting either of these properties to `NULL` will disable using the corresponding configuration file (DSN will exist only in memory and their definition will be lost when the application finishes).

The GdaConfig object implements its own locking mechanism so it is thread-safe.

## Details

### GdaConfig

    typedef struct _GdaConfig GdaConfig;

### GdaDsnInfo

    typedef struct {
            gchar    *name;        /* plain text, not RFC 1738 encoded */
            gchar    *provider;    /* plain text, not RFC 1738 encoded */
            gchar    *description; /* plain text, not RFC 1738 encoded */
            gchar    *cnc_string;  /* semi-colon separated <key>=<value> list where <key> and <value> are RFC 1738 encoded */
            gchar    *auth_string; /* semi-colon separated <key>=<value> list where <key> and <value> are RFC 1738 encoded */
            gboolean  is_system;

    	/* Padding for future expansion */
    	gpointer _gda_reserved1;
    	gpointer _gda_reserved2;
    	gpointer _gda_reserved3;
    	gpointer _gda_reserved4;
    } GdaDsnInfo;

### gda_config_get_dsn_info ()

    GdaDsnInfo *        gda_config_get_dsn_info             (const gchar *dsn_name);

Get information about the DSN named `dsn_name`.

`dsn_name`'s format is "[<username>[:<password>]@]<DSN>" (if <username> and optionaly <password> are provided, they are ignored). Also see the `gda_dsn_split()` utility function.

`dsn_name` : | the name of the DSN to look for
Returns : | a a pointer to read-only GdaDsnInfo structure, or `NULL` if not found

### gda_config_define_dsn ()

    gboolean            gda_config_define_dsn               (const GdaDsnInfo *info,
                                                             GError **error);

Add or update a DSN from the definition in `info`

`info` : | a pointer to a filled GdaDsnInfo structure
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred

### gda_config_remove_dsn ()

    gboolean            gda_config_remove_dsn               (const gchar *dsn_name,
                                                             GError **error);

Add or update a DSN from the definition in `info`

`dsn_name` : | the name of the DSN to remove
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred

### gda_config_dsn_needs_authentication ()

    gboolean            gda_config_dsn_needs_authentication (const gchar *dsn_name);

Tells if the data source identified as `dsn_name` needs any authentication. If a <username> and optionaly a <password> are specified, they are ignored.

`dsn_name` : | the name of a DSN, in the "[<username>[:<password>]@]<DSN>" format
Returns : | TRUE if an authentication is needed

### gda_config_list_dsn ()

    GdaDataModel *      gda_config_list_dsn                 (void);

Get a GdaDataModel representing all the configured DSN, and keeping itself up to date with the changes in the declared DSN.

The returned data model is composed of the following columns:

- DSN name

- Provider name

- Description

- Connection string

- Username if it exists

Returns : | a new GdaDataModel

### gda_config_get_nb_dsn ()

    gint                gda_config_get_nb_dsn               (void);

Get the number of defined DSN

Returns : | the number of defined DSN

### gda_config_get_dsn_info_index ()

    gint                gda_config_get_dsn_info_index       (const gchar *dsn_name);

Get the index (starting at 0) of the DSN named `dsn_name`

`dsn_name` : | a DSN
Returns : | the index or -1 if not found

### gda_config_get_dsn_info_at_index ()

    GdaDsnInfo *        gda_config_get_dsn_info_at_index    (gint index);

Get a pointer to a read-only GdaDsnInfo at the `index` position

`index` : | an index
Returns : | the pointer or `NULL` if no DSN exists at position `index`

### gda_config_can_modify_system_config ()

    gboolean            gda_config_can_modify_system_config (void);

Tells if the global (system) configuration can be modified (considering system permissions and settings)

Returns : | TRUE if system-wide configuration can be modified

### GdaProviderInfo

    typedef struct {
            gchar             *id;
            gchar             *location;
            gchar             *description;
            GdaSet            *dsn_params;  /* Specs to create a DSN */
    	GdaSet            *auth_params; /* Specs to authenticate a client */

    	/* Padding for future expansion */
    	gpointer _gda_reserved1;
    	gpointer _gda_reserved2;
    	gpointer _gda_reserved3;
    	gpointer _gda_reserved4;
    } GdaProviderInfo;

### gda_config_get_provider_info ()

    GdaProviderInfo *   gda_config_get_provider_info        (const gchar *provider_name);

Get some information about the a database provider (adaptator) named

`provider_name` : | a database provider
Returns : | a pointer to read-only GdaProviderInfo structure, or `NULL` if not found

### gda_config_get_provider ()

    GdaServerProvider * gda_config_get_provider             (const gchar *provider_name,
                                                             GError **error);

Get a pointer to the session-wide GdaServerProvider for the provider named `provider_name`. The caller must not call `g_object_unref()` on the returned object.

`provider_name` : | a database provider
`error` : | a place to store errors, or `NULL`
Returns : | a pointer to the GdaServerProvider, or `NULL` if an error occurred

### gda_config_list_providers ()

    GdaDataModel *      gda_config_list_providers           (void);

Get a GdaDataModel representing all the installed database providers.

The returned data model is composed of the following columns:

- Provider name

- Description

- DSN parameters

- Authentication parameters

- File name of the plugin

Returns : | a new GdaDataModel

### gda_config_get ()

    GdaConfig*          gda_config_get                      (void);

Get a pointer to the global GdaConfig object

Returns : | a non `NULL` pointer to a GdaConfig

## Property Details

### The `"system-filename"` property

      "system-filename"          gchar*                : Read / Write

File to use for system-wide DSN list.

Default value: NULL

### The `"user-filename"` property

      "user-filename"            gchar*                : Read / Write

File to use for per-user DSN list.

Default value: NULL

## Signal Details

### The `"dsn-added"` signal

    void                user_function                      (GdaConfig *conf,
                                                            gpointer   new_dsn,
                                                            gpointer   user_data)      : Run First

Gets emitted whenever a new DSN has been defined

`conf` : | the GdaConfig object
`new_dsn` : | a GdaDsnInfo
`user_data` : | user data set when the signal handler was connected.

### The `"dsn-changed"` signal

    void                user_function                      (GdaConfig *conf,
                                                            gpointer   dsn,
                                                            gpointer   user_data)      : Run First

Gets emitted whenever a DSN's definition has been changed

`conf` : | the GdaConfig object
`dsn` : | a GdaDsnInfo
`user_data` : | user data set when the signal handler was connected.

### The `"dsn-removed"` signal

    void                user_function                      (GdaConfig *conf,
                                                            gpointer   old_dsn,
                                                            gpointer   user_data)      : Run First

Gets emitted whenever a DSN has been removed

`conf` : | the GdaConfig object
`old_dsn` : | a GdaDsnInfo
`user_data` : | user data set when the signal handler was connected.

### The `"dsn-to-be-removed"` signal

    void                user_function                      (GdaConfig *conf,
                                                            gpointer   old_dsn,
                                                            gpointer   user_data)      : Run First

Gets emitted whenever a DSN is about to be removed

`conf` : | the GdaConfig object
`old_dsn` : | a GdaDsnInfo
`user_data` : | user data set when the signal handler was connected.