GdaClient

GdaClient — Database client access

Synopsis

                    GdaClient;
enum                GdaClientEvent;
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,
                                                         const gchar *username,
                                                         const gchar *password,
                                                         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);
gboolean            gda_client_begin_transaction        (GdaClient *client,
                                                         const gchar *name,
                                                         GdaTransactionIsolation level,
                                                         GError **error);
gboolean            gda_client_commit_transaction       (GdaClient *client,
                                                         const gchar *name,
                                                         GError **error);
gboolean            gda_client_rollback_transaction     (GdaClient *client,
                                                         const gchar *name,
                                                         GError **error);
gchar *             gda_client_get_dsn_specs            (GdaClient *client,
                                                         const gchar *provider);
GdaServerOperation * gda_client_prepare_create_database (GdaClient *client,
                                                         const gchar *db_name,
                                                         const gchar *provider);
gboolean            gda_client_perform_create_database  (GdaClient *client,
                                                         GdaServerOperation *op,
                                                         GError **error);
GdaServerOperation * gda_client_prepare_drop_database   (GdaClient *client,
                                                         const gchar *db_name,
                                                         const gchar *provider);
gboolean            gda_client_perform_drop_database    (GdaClient *client,
                                                         GdaServerOperation *op,
                                                         GError **error);

Object Hierarchy

  GObject
   +----GdaClient

Signals

  "event-notification"                             : Run Last

Description

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.

Details

GdaClient

typedef struct _GdaClient GdaClient;


enum GdaClientEvent

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;


gda_client_new ()

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.

gda_client_declare_connection ()

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

gda_client_open_connection ()

GdaConnection *     gda_client_open_connection          (GdaClient *client,
                                                         const gchar *dsn,
                                                         const gchar *username,
                                                         const gchar *password,
                                                         GdaConnectionOptions options,
                                                         GError **error);

This function is the way of opening database connections with libgda.

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.

The username and password used to actually open the connection are the first non-NULL string being chosen by order from

  • the username or password
  • the username or password sprcified in the DSN definition
  • the USERNAME= and PASSWORD= parts of the connection string in the DSN definition

If a new GdaConnection is created, then the caller will hold a reference on it, and if a GdaConnection already existing is used, then the reference count of that object will be increased by one.

client :

a GdaClient object.

dsn :

data source name.

username :

user name or NULL

password :

password for username, or NULL

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 was an error.

gda_client_open_connection_from_string ()

GdaConnection *     gda_client_open_connection_from_string
                                                        (GdaClient *client,
                                                         const gchar *provider_id,
                                                         const gchar *cnc_string,
                                                         const gchar *username,
                                                         const gchar *password,
                                                         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 semicolumn-separated series of key=value pairs. Do not add extra whitespace after the semicolumn separator. The possible keys depend on the provider, the "gda-sql-3.0 -L" command can be used to list the actual keys for each installed database provider.

For example the connection string to open an SQLite connection to a database file named "my_data.db" in the current directory would be "DB_DIR=.;DB_NAME=my_data".

The username and password used to actually open the connection are the first non-NULL string being chosen by order from

  • the username or password
  • the USERNAME= and PASSWORD= parts of the cnc_string

Additionnally, it is possible to have the connection string respect the "<provider_name>://<real cnc string>" format, in which case the provider name and the real connection string will be extracted from that string (note that if provider_id is not NULL then it will still be used as the provider ID).

client :

a GdaClient object.

provider_id :

provider ID to connect to, or NULL

cnc_string :

connection string.

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.

gda_client_get_connections ()

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

gda_client_find_connection ()

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.

gda_client_close_all_connections ()

void                gda_client_close_all_connections    (GdaClient *client);

Closes all connections opened by the given GdaClient object.

client :

a GdaClient object.

gda_client_notify_event ()

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.

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

gda_client_notify_connection_opened_event ()

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.

gda_client_notify_connection_closed_event ()

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.

gda_client_begin_transaction ()

gboolean            gda_client_begin_transaction        (GdaClient *client,
                                                         const gchar *name,
                                                         GdaTransactionIsolation level,
                                                         GError **error);

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.

name :

the name of the transation to start

error :

a place to store errors, or NULL

Returns :

TRUE if all transactions could be started successfully, or FALSE if one of them fails.

gda_client_commit_transaction ()

gboolean            gda_client_commit_transaction       (GdaClient *client,
                                                         const gchar *name,
                                                         GError **error);

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.

name :

the name of the transation to commit

error :

a place to store errors, or NULL

Returns :

TRUE if all transactions could be committed successfully, or FALSE if one of them fails.

gda_client_rollback_transaction ()

gboolean            gda_client_rollback_transaction     (GdaClient *client,
                                                         const gchar *name,
                                                         GError **error);

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.

name :

the name of the transation to rollback

error :

a place to store errors, or NULL

Returns :

TRUE if all transactions could be cancelled successfully, or FALSE if one of them fails.

gda_client_get_dsn_specs ()

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 occurred

gda_client_prepare_create_database ()

GdaServerOperation * gda_client_prepare_create_database (GdaClient *client,
                                                         const gchar *db_name,
                                                         const gchar *provider);

Creates a new GdaServerOperation object which contains the specifications required to create a database. Once these specifications provided, use gda_client_perform_create_database() to perform the database creation.

If db_name is left NULL, then the name of the database to create will have to be set in the returned GdaServerOperation using gda_server_operation_set_value_at().

client :

a GdaClient object.

db_name :

the name of the database to create, or NULL

provider :

a provider

Returns :

new GdaServerOperation object, or NULL if the provider does not support database creation

gda_client_perform_create_database ()

gboolean            gda_client_perform_create_database  (GdaClient *client,
                                                         GdaServerOperation *op,
                                                         GError **error);

Creates a new database using the specifications in op, which must have been obtained using gda_client_prepare_create_database()

client :

a GdaClient object.

op :

a GdaServerOperation object obtained using gda_client_prepare_create_database()

error :

a place to store en error, or NULL

Returns :

TRUE if no error occurred and the database has been created

gda_client_prepare_drop_database ()

GdaServerOperation * gda_client_prepare_drop_database   (GdaClient *client,
                                                         const gchar *db_name,
                                                         const gchar *provider);

Creates a new GdaServerOperation object which contains the specifications required to drop a database. Once these specifications provided, use gda_client_perform_drop_database() to perform the database creation.

If db_name is left NULL, then the name of the database to drop will have to be set in the returned GdaServerOperation using gda_server_operation_set_value_at().

client :

a GdaClient object.

db_name :

the name of the database to drop, or NULL

provider :

a provider

Returns :

new GdaServerOperation object, or NULL if the provider does not support database destruction

gda_client_perform_drop_database ()

gboolean            gda_client_perform_drop_database    (GdaClient *client,
                                                         GdaServerOperation *op,
                                                         GError **error);

Destroys an existing database using the specifications in op, which must have been obtained using gda_client_prepare_drop_database()

client :

a GdaClient object.

op :

a GdaServerOperation object obtained using gda_client_prepare_drop_database()

error :

a place to store en error, or NULL

Returns :

TRUE if no error occurred and the database has been destroyed

Signal Details

The "event-notification" signal

void                user_function                      (GdaClient        *gdaclient,
                                                        GdaConnection    *arg1,
                                                        GdaClientEvent    arg2,
                                                        GdaParameterList *arg3,
                                                        gpointer          user_data)      : Run Last

gdaclient :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

See Also

GdaConnection.