Configuration

Configuration

Synopsis

                    GdaConfig;

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

struct              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

Details

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

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

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.

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

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

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.

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

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

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.

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

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

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

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]

Property Details

The "system-filename" property

  "system-filename"          gchar*                : Read / Write

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

Default value: NULL


The "user-filename" property

  "user-filename"            gchar*                : Read / Write

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

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.