![]() |
![]() |
![]() |
GNOME Data Access 4 manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
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
);
"dsn-added" : Run First "dsn-changed" : Run First "dsn-removed" : Run First "dsn-to-be-removed" : Run First
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()
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.
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; } GdaDsnInfo;
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.
|
the name of the DSN to look for |
Returns : |
a pointer to read-only GdaDsnInfo structure, or NULL if not found. [transfer none]
|
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).
|
a pointer to a filled GdaDsnInfo structure |
|
a place to store errors, or NULL
|
Returns : |
TRUE if no error occurred |
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).
|
the name of the DSN to remove |
|
a place to store errors, or NULL
|
Returns : |
TRUE if no error occurred |
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.
|
the name of a DSN, in the "[<username>[:<password>]@]<DSN>" format |
Returns : |
TRUE if an authentication is needed |
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] |
gint gda_config_get_nb_dsn (void
);
Get the number of defined DSN
Returns : |
the number of defined DSN |
gint gda_config_get_dsn_info_index (const gchar *dsn_name
);
Get the index (starting at 0) of the DSN named dsn_name
|
a DSN |
Returns : |
the index or -1 if not found |
GdaDsnInfo * gda_config_get_dsn_info_at_index (gint index
);
Get a pointer to a read-only GdaDsnInfo at the index
position
|
an index |
Returns : |
the pointer or NULL if no DSN exists at position index . [transfer none]
|
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 |
typedef struct { gchar *id; gchar *location; gchar *description; GdaSet *dsn_params; /* Specs to create a DSN */ GdaSet *auth_params; /* Specs to authenticate a client */ } GdaProviderInfo;
GdaProviderInfo * gda_config_get_provider_info (const gchar *provider_name
);
Get some information about the a database provider (adapter) named
|
a database provider |
Returns : |
a pointer to read-only GdaProviderInfo structure, or NULL if not found. [transfer none]
|
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).
|
a database provider |
|
a place to store errors, or NULL
|
Returns : |
a pointer to the GdaServerProvider, or NULL if an error occurred. [transfer none]
|
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] |
GdaConfig* gda_config_get (void
);
Get a pointer to the global GdaConfig object
Returns : |
a non NULL pointer to a GdaConfig. [transfer full]
|
"system-filename"
property"system-filename" gchar* : Read / Write
File to use for system-wide DSN list.
Default value: NULL
"user-filename"
property"user-filename" gchar* : Read / Write
File to use for per-user DSN list.
Default value: NULL
"dsn-added"
signalvoid user_function (GdaConfig *conf, gpointer new_dsn, gpointer user_data) : Run First
Gets emitted whenever a new DSN has been defined
@: @:
|
the GdaConfig object |
|
a GdaDsnInfo |
|
user data set when the signal handler was connected. |
"dsn-changed"
signalvoid user_function (GdaConfig *conf, gpointer dsn, gpointer user_data) : Run First
Gets emitted whenever a DSN's definition has been changed
@: @:
|
the GdaConfig object |
|
a GdaDsnInfo |
|
user data set when the signal handler was connected. |
"dsn-removed"
signalvoid user_function (GdaConfig *conf, gpointer old_dsn, gpointer user_data) : Run First
Gets emitted whenever a DSN has been removed
@: @:
|
the GdaConfig object |
|
a GdaDsnInfo |
|
user data set when the signal handler was connected. |
"dsn-to-be-removed"
signalvoid user_function (GdaConfig *conf, gpointer old_dsn, gpointer user_data) : Run First
Gets emitted whenever a DSN is about to be removed
@: @:
|
the GdaConfig object |
|
a GdaDsnInfo |
|
user data set when the signal handler was connected. |