![]() |
![]() |
![]() |
GNOME Data Access manual | ![]() |
---|
GdaClientGdaClient — Database client access |
GdaClient; enum GdaClientEvent; enum GdaClientSpecsType; GdaClient* gda_client_new (void); void gda_client_declare_connection (GdaClient *client, GdaConnection *cnc); GdaConnection* gda_client_open_connection (GdaClient *client, const gchar *dsn, const gchar *username, const gchar *password, GdaConnectionOptions options, GError **error); GdaConnection* gda_client_open_connection_from_string (GdaClient *client, const gchar *provider_id, const gchar *cnc_string, GdaConnectionOptions options, GError **error); const GList* gda_client_get_connections (GdaClient *client); GdaConnection* gda_client_find_connection (GdaClient *client, const gchar *dsn, const gchar *username, const gchar *password); void gda_client_close_all_connections (GdaClient *client); void gda_client_notify_event (GdaClient *client, GdaConnection *cnc, GdaClientEvent event, GdaParameterList *params); void gda_client_notify_error_event (GdaClient *client, GdaConnection *cnc, GdaConnectionEvent *error); void gda_client_notify_connection_opened_event (GdaClient *client, GdaConnection *cnc); void gda_client_notify_connection_closed_event (GdaClient *client, GdaConnection *cnc); void gda_client_notify_transaction_started_event (GdaClient *client, GdaConnection *cnc, GdaTransaction *xaction); void gda_client_notify_transaction_committed_event (GdaClient *client, GdaConnection *cnc, GdaTransaction *xaction); void gda_client_notify_transaction_cancelled_event (GdaClient *client, GdaConnection *cnc, GdaTransaction *xaction); gboolean gda_client_begin_transaction (GdaClient *client, GdaTransaction *xaction); gboolean gda_client_commit_transaction (GdaClient *client, GdaTransaction *xaction); gboolean gda_client_rollback_transaction (GdaClient *client, GdaTransaction *xaction); gchar* gda_client_get_dsn_specs (GdaClient *client, const gchar *provider); gchar* gda_client_get_provider_specs (GdaClient *client, const gchar *provider, GdaClientSpecsType type); gboolean gda_client_create_database (GdaClient *client, const gchar *provider, GdaParameterList *params, GError **error); gboolean gda_client_drop_database (GdaClient *client, const gchar *provider, GdaParameterList *params, GError **error);
"event-notification" void user_function (GdaClient *gdaclient, gpointer arg1, gint arg2, gpointer arg3, gpointer user_data);
This class is the main entry point for libgda client applications. It provides the way by which client applications open connections. Thus, before using any other database-oriented function in libgda, applications must create a GdaClient object (via gda_client_new), and, once created, open the connections from it.
GdaClient also provides a way to treat several connections as if they were only one (a connection pool), which allows applications to, for instance, commit/rollback a transaction in all the connections being managed by a unique GdaClient object, or obtain the list of all tables in all opened connections.
Database creation and destruction is done through a GdaClient object uding the
gda_client_create_database()
and gda_client_drop_database()
methods. Note however that
depending on the provider, an opened connection may be required in order to create
or destroy a database.
typedef enum { GDA_CLIENT_EVENT_INVALID, /* events usually notified by the library itself, and which the providers should notify on very special cases (like a transaction being started or committed via a BEGIN/COMMIT command directly sent to the execute_command method on the provider */ GDA_CLIENT_EVENT_ERROR, /* params: "error" */ GDA_CLIENT_EVENT_CONNECTION_OPENED, /* params: */ GDA_CLIENT_EVENT_CONNECTION_CLOSED, /* params: */ GDA_CLIENT_EVENT_TRANSACTION_STARTED, /* params: "transaction" */ GDA_CLIENT_EVENT_TRANSACTION_COMMITTED, /* params: "transaction" */ GDA_CLIENT_EVENT_TRANSACTION_CANCELLED, /* params: "transaction" */ } GdaClientEvent;
typedef enum { GDA_CLIENT_SPECS_CREATE_DATABASE, GDA_CLIENT_SPECS_DROP_DATABASE } GdaClientSpecsType;
GdaClient* gda_client_new (void);
Creates a new GdaClient object, which is the entry point for libgda client applications. This object, once created, can be used for opening new database connections and activating other services available to GDA clients.
Returns : | the newly created object. |
void gda_client_declare_connection (GdaClient *client, GdaConnection *cnc);
Declares the cnc
to client
. This function should not be used directly
client : |
a GdaClient object |
cnc : |
a GdaConnection object |
GdaConnection* gda_client_open_connection (GdaClient *client, const gchar *dsn, const gchar *username, const gchar *password, GdaConnectionOptions options, GError **error);
Establishes a connection to a data source. The connection will be opened
if no identical connection is available in the GdaClient connection pool,
and re-used if available. If you dont want to share the connection,
specify GDA_CONNECTION_OPTIONS_DONT_SHARE as one of the flags in
the options
parameter.
This function is the way of opening database connections with libgda.
client : |
a GdaClient object. |
dsn : |
data source name. |
username : |
user name. |
password : |
password for username .
|
options : |
options for the connection (see GdaConnectionOptions). |
error : |
a place to store an error, or NULL
|
Returns : | the opened connection if successful, NULL if there is
an error.
|
GdaConnection* gda_client_open_connection_from_string (GdaClient *client, const gchar *provider_id, const gchar *cnc_string, GdaConnectionOptions options, GError **error);
Opens a connection given a provider ID and a connection string. This
allows applications to open connections without having to create
a data source in the configuration. The format of cnc_string
is
similar to PostgreSQL and MySQL connection strings. It is a ;-separated
series of key=value pairs. Do not add extra whitespace after the ;
separator. The possible keys depend on the provider, but
these keys should work with all providers:
USER, PASSWORD, HOST, DATABASE, PORT
client : |
a GdaClient object. |
provider_id : |
provider ID to connect to. |
cnc_string : |
connection string. |
options : |
options for the connection (see GdaConnectionOptions). |
error : |
a place to store an error, or NULL
|
Returns : | the opened connection if successful, NULL if there is
an error.
|
const GList* gda_client_get_connections (GdaClient *client);
Gets the list of all open connections in the given GdaClient object. The GList returned is an internal pointer, so DON'T TRY TO FREE IT.
client : |
a GdaClient object. |
Returns : | a GList of GdaConnection objects; dont't modify that list |
GdaConnection* gda_client_find_connection (GdaClient *client, const gchar *dsn, const gchar *username, const gchar *password);
Looks for an open connection given a data source name (per libgda configuration), a username and a password.
This function iterates over the list of open connections in the given GdaClient and looks for one that matches the given data source name, username and password.
client : |
a GdaClient object. |
dsn : |
data source name. |
username : |
user name. |
password : |
password for username .
|
Returns : | a pointer to the found connection, or NULL if it could not
be found.
|
void gda_client_close_all_connections (GdaClient *client);
Closes all connections opened by the given GdaClient object.
client : |
a GdaClient object. |
void gda_client_notify_event (GdaClient *client, GdaConnection *cnc, GdaClientEvent event, GdaParameterList *params);
Notifies an event to the given GdaClient's listeners. The event can be anything (see GdaClientEvent) ranging from a connection opening operation, to changes made to a table in an underlying database.
client : |
a GdaClient object. |
cnc : |
a GdaConnection object where the event has occurred. |
event : |
event ID. |
params : |
parameters associated with the event. |
void gda_client_notify_error_event (GdaClient *client, GdaConnection *cnc, GdaConnectionEvent *error);
Notifies the given GdaClient of the GDA_CLIENT_EVENT_ERROR event.
client : |
a GdaClient object. |
cnc : |
a GdaConnection object. |
error : |
the error to be notified. |
void gda_client_notify_connection_opened_event (GdaClient *client, GdaConnection *cnc);
Notifies the given GdaClient of the GDA_CLIENT_EVENT_CONNECTION_OPENED event.
client : |
a GdaClient object. |
cnc : |
a GdaConnection object. |
void gda_client_notify_connection_closed_event (GdaClient *client, GdaConnection *cnc);
Notifies the given GdaClient of the GDA_CLIENT_EVENT_CONNECTION_CLOSED event.
client : |
a GdaClient object. |
cnc : |
a GdaConnection object. |
void gda_client_notify_transaction_started_event (GdaClient *client, GdaConnection *cnc, GdaTransaction *xaction);
Notifies the given GdaClient of the GDA_CLIENT_EVENT_TRANSACTION_STARTED event.
client : |
a GdaClient object. |
cnc : |
a GdaConnection object. |
xaction : |
a GdaTransaction object. |
void gda_client_notify_transaction_committed_event (GdaClient *client, GdaConnection *cnc, GdaTransaction *xaction);
Notifies the given GdaClient of the GDA_CLIENT_EVENT_TRANSACTION_COMMITTED event.
client : |
a GdaClient object. |
cnc : |
a GdaConnection object. |
xaction : |
a GdaTransaction object. |
void gda_client_notify_transaction_cancelled_event (GdaClient *client, GdaConnection *cnc, GdaTransaction *xaction);
Notifies the given GdaClient of the GDA_CLIENT_EVENT_TRANSACTION_CANCELLED event.
client : |
a GdaClient object. |
cnc : |
a GdaConnection object. |
xaction : |
a GdaTransaction object. |
gboolean gda_client_begin_transaction (GdaClient *client, GdaTransaction *xaction);
Starts a transaction on all connections being managed by the given GdaClient. It is important to note that this operates on all connections opened within a GdaClient, which could not be what you're looking for.
To execute a transaction on a unique connection, use gda_connection_begin_transaction, gda_connection_commit_transaction and gda_connection_rollback_transaction.
client : |
a GdaClient object. |
xaction : |
a GdaTransaction object. |
Returns : | TRUE if all transactions could be started successfully,
or FALSE if one of them fails.
|
gboolean gda_client_commit_transaction (GdaClient *client, GdaTransaction *xaction);
Commits a running transaction on all connections being managed by the given GdaClient. It is important to note that this operates on all connections opened within a GdaClient, which could not be what you're looking for.
To execute a transaction on a unique connection, use gda_connection_begin_transaction, gda_connection_commit_transaction and gda_connection_rollback_transaction.
client : |
a GdaClient object. |
xaction : |
a GdaTransaction object. |
Returns : | TRUE if all transactions could be committed successfully,
or FALSE if one of them fails.
|
gboolean gda_client_rollback_transaction (GdaClient *client, GdaTransaction *xaction);
Cancels a running transaction on all connections being managed by the given GdaClient. It is important to note that this operates on all connections opened within a GdaClient, which could not be what you're looking for.
To execute a transaction on a unique connection, use gda_connection_begin_transaction, gda_connection_commit_transaction and gda_connection_rollback_transaction.
client : |
a GdaClient object. |
xaction : |
a GdaTransaction object. |
Returns : | TRUE if all transactions could be cancelled successfully,
or FALSE if one of them fails.
|
gchar* gda_client_get_dsn_specs (GdaClient *client, const gchar *provider);
Get an XML string representing the parameters which can be present in the DSN string used to open a connection.
client : |
a GdaClient object. |
provider : |
a provider |
Returns : | a string (free it after usage), or NULL if an error occured
|
gchar* gda_client_get_provider_specs (GdaClient *client, const gchar *provider, GdaClientSpecsType type);
Get an XML string representing the parameters required to perform a specific action
using the provider
provider. The action to perform is chosen by the type
argument.
For example to create a database, make a list of GdaParameter
objects for each parameter listed in the returned XML string, and use it to call
gda_client_create_database()
.
client : |
a GdaClient object. |
provider : |
a provider |
type : |
a GdaClientSpecsType type |
Returns : | a string (free it after usage), or NULL if the provider does not implement database
creation
|
gboolean gda_client_create_database (GdaClient *client, const gchar *provider, GdaParameterList *params, GError **error);
Creates a new database using the specifications in params
. The list of parameters to
provide to create a database depends of the provider being used, and can be obtained using
the gda_client_get_provider_specs()
function.
For the providers which do not yet implement the gda_client_get_provider_specs()
method, create a list with a GdaParameter object for
an opened GdaConnection object, named "cnc"
the name of the database to create, named "dbname"
client : |
a GdaClient object. |
provider : |
a provider |
params : |
|
error : |
a place to store en error, or NULL
|
Returns : | TRUE if no error occured and the database has been created |
gboolean gda_client_drop_database (GdaClient *client, const gchar *provider, GdaParameterList *params, GError **error);
Destroys an existing database using the specifications in params
. The list of parameters to
provide to destroy a database depends of the provider being used, and can be obtained using
the gda_client_get_provider_specs()
function.
For the providers which do not yet implement the gda_client_get_provider_specs()
method, create a list with a GdaParameter object for
an opened GdaConnection object, named "cnc"
the name of the database to destroy, named "dbname"
client : |
a GdaClient object. |
provider : |
a provider |
params : |
|
error : |
a place to store en error, or NULL
|
Returns : | TRUE if no error occured and the database has been destroyed |
void user_function (GdaClient *gdaclient, gpointer arg1, gint arg2, gpointer arg3, gpointer user_data);
gdaclient : |
the object which received the signal. |
arg1 : |
|
arg2 : |
|
arg3 : |
|
user_data : |
user data set when the signal handler was connected. |
<< Connections & commands | GdaConnection >> |