Configuration: GNOME Data Access 5 manual

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

## Stability Level

Stable, unless otherwise indicated

## Functions

GdaDsnInfo * | gda_config_get_dsn_info ()
gboolean | gda_config_define_dsn ()
gboolean | gda_config_remove_dsn ()
gboolean | gda_config_dsn_needs_authentication ()
GdaDataModel * | gda_config_list_dsn ()
gint | gda_config_get_nb_dsn ()
gint | gda_config_get_dsn_info_index ()
GdaDsnInfo * | gda_config_get_dsn_info_at_index ()
gboolean | gda_config_can_modify_system_config ()
GdaProviderInfo * | gda_config_get_provider_info ()
GdaServerProvider * | gda_config_get_provider ()
GdaDataModel * | gda_config_list_providers ()
GdaConfig * | gda_config_get ()

## Properties

gchar * | system-filename | Read / Write
gchar * | user-filename | Read / Write

## Signals

void | dsn-added | Run First
void | dsn-changed | Run First
void | dsn-removed | Run First
void | dsn-to-be-removed | Run First

## Types and Values

| GdaConfig
struct | GdaDsnInfo
struct | GdaProviderInfo

## Object Hierarchy

        GObject
        ╰── GdaConfig

## Description

The functions in this section allow applications an easy access to libgda's configuration (the list of data sources and database providers).

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-filename", "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 pointless 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.

Note about localization: when the GdaConfig loads configuration files, it filters the contents based on the current locale, so for example if your current locale is "de" then all the loaded strings (for the ones which are translated) will be in the German language. Changing the locale afterwards will have no effect on the GdaConfig and the already loaded configuration. The consequence is that you should first call `setlocale()` youself in your code before using a GdaConfig object. As a side note you should also call `gtk_init()` before `gdaui_init()` because `gtk_init()` calls `setlocale()`.

## Functions

### 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 optionally <password> are provided, they are ignored). Also see the `gda_dsn_split()` utility function.

#### Parameters

dsn_name | the name of the DSN to look for |

#### Returns

a pointer to read-only GdaDsnInfo structure, or `NULL` if not found.

[transfer none]

### gda_config_define_dsn ()

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

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

This method may fail with a `GDA_CONFIG_ERROR` domain error (see the GdaConfigError error codes).

#### Parameters

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);

Remove the DSN named `dsn_name` .

This method may fail with a `GDA_CONFIG_ERROR` domain error (see the GdaConfigError error codes).

#### Parameters

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 optionally a <password> are specified, they are ignored.

#### Parameters

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.

[transfer full]

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

#### Parameters

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

#### Parameters

index | an index |

#### Returns

the pointer or `NULL` if no DSN exists at position `index` .

[transfer none]

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

### gda_config_get_provider_info ()

    GdaProviderInfo *
    gda_config_get_provider_info (const gchar *provider_name);

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

#### Parameters

provider_name | a database provider |

#### Returns

a pointer to read-only GdaProviderInfo structure, or `NULL` if not found.

[transfer none]

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

This method may fail with a `GDA_CONFIG_ERROR` domain error (see the GdaConfigError error codes).

#### Parameters

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.

[transfer none]

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

[transfer full]

### gda_config_get ()

    GdaConfig *
    gda_config_get (void);

Get a pointer to the global (unique) GdaConfig object. This functions increments the reference count of the object, so you need to call `g_object_unref()` on it once finished.

#### Returns

a non `NULL` pointer to the unique GdaConfig.

[transfer full]

## Types and Values

### GdaConfig

    typedef struct _GdaConfig GdaConfig;

### struct GdaDsnInfo

    struct GdaDsnInfo {
            gchar    *name;
            gchar    *provider;
            gchar    *description;
            gchar    *cnc_string;
            gchar    *auth_string;
            gboolean  is_system;
    };

This structure defines the properties of a named data source (DSN).

#### Members

gchar *`name`; | the (unique) name of the DSN (plain text, not RFC 1738 encoded) |
gchar *`provider`; | the ID of the database provider to be used (plain text, not RFC 1738 encoded) |
gchar *`description`; | a descriptive string (plain text, not RFC 1738 encoded), can be `NULL`. |
gchar *`cnc_string`; | the connection string, a semi-colon separated <key>=<value> list where <key> and <value> are RFC 1738 encoded |
gchar *`auth_string`; | the authentication string, a semi-colon separated <key>=<value> list where <key> and <value> are RFC 1738 encoded. Can be `NULL`. |
gboolean `is_system`; | `TRUE` if the DSN is a system wide defined data source |

### struct GdaProviderInfo

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

This structure holds the information associated to a database provider as discovered by Libgda.

#### Members

gchar *`id`; | the unique identifier of the database provider |
gchar *`location`; | the complete path to the shared library implementing the database provider |
gchar *`description`; | provider's description |
GdaSet *`dsn_params`; | a GdaSet containing all the parameters which can/must be specified when opening a connection or defining a named data source (DSN) |
GdaSet *`auth_params`; | a GdaSet containing all the authentication parameters |

## Property Details

### The `“system-filename”` property

      “system-filename”          gchar *

File to use for system-wide DSN list. When changed, the whole list of DSN will be reloaded.

Flags: Read / Write

Default value: NULL

### The `“user-filename”` property

      “user-filename”            gchar *

File to use for per-user DSN list. When changed, the whole list of DSN will be reloaded.

Flags: Read / Write

Default value: NULL

## Signal Details

### The `“dsn-added”` signal

    void
    user_function (GdaConfig *conf,
                   gpointer   new_dsn,
                   gpointer   user_data)

Gets emitted whenever a new DSN has been defined

#### Parameters

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

Flags: Run First

### The `“dsn-changed”` signal

    void
    user_function (GdaConfig *conf,
                   gpointer   dsn,
                   gpointer   user_data)

Gets emitted whenever a DSN's definition has been changed

#### Parameters

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

Flags: Run First

### The `“dsn-removed”` signal

    void
    user_function (GdaConfig *conf,
                   gpointer   old_dsn,
                   gpointer   user_data)

Gets emitted whenever a DSN has been removed

#### Parameters

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

Flags: Run First

### The `“dsn-to-be-removed”` signal

    void
    user_function (GdaConfig *conf,
                   gpointer   old_dsn,
                   gpointer   user_data)

Gets emitted whenever a DSN is about to be removed

#### Parameters

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

Flags: Run First