GdaClient

GdaClient — Database client access

Functions

Types and Values

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.

Functions

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_open_connection ()

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

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.

Parameters

client

a GdaClient object.

 

dsn

data source name.

 

username

user name.

 

password

password for username .

 

options

options for the connection (see GdaConnectionOptions).

 

Returns

the opened connection if successful, NULL if there is 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,
                                GdaConnectionOptions options);

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

Parameters

client

a GdaClient object.

 

provider_id

provider ID to connect to.

 

cnc_string

connection string.

 

options

options for the connection (see GdaConnectionOptions).

 

Returns

the opened connection if successful, NULL if there is an error.


gda_client_get_connection_list ()

const GList *
gda_client_get_connection_list (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.

Parameters

client

a GdaClient object.

 

Returns

a GList of GdaConnection objects.


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.

Parameters

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.

Parameters

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.

Parameters

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,
                               GdaError *error);

Notifies the given GdaClient of the GDA_CLIENT_EVENT_ERROR event.

Parameters

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.

Parameters

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.

Parameters

client

a GdaClient object.

 

cnc

a GdaConnection object.

 

gda_client_notify_transaction_started_event ()

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.

Parameters

client

a GdaClient object.

 

cnc

a GdaConnection object.

 

xaction

a GdaTransaction object.

 

gda_client_notify_transaction_committed_event ()

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.

Parameters

client

a GdaClient object.

 

cnc

a GdaConnection object.

 

xaction

a GdaTransaction object.

 

gda_client_notify_transaction_cancelled_event ()

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.

Parameters

client

a GdaClient object.

 

cnc

a GdaConnection object.

 

xaction

a GdaTransaction object.

 

gda_client_begin_transaction ()

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.

Parameters

client

a GdaClient object.

 

xaction

a GdaTransaction object.

 

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

Parameters

client

a GdaClient object.

 

xaction

a GdaTransaction object.

 

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

Parameters

client

a GdaClient object.

 

xaction

a GdaTransaction object.

 

Returns

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

Types and Values

enum GdaClientEvent

Members

GDA_CLIENT_EVENT_INVALID

   

GDA_CLIENT_EVENT_ERROR

   

GDA_CLIENT_EVENT_CONNECTION_OPENED

   

GDA_CLIENT_EVENT_CONNECTION_CLOSED

   

GDA_CLIENT_EVENT_TRANSACTION_STARTED

   

GDA_CLIENT_EVENT_TRANSACTION_COMMITTED

   

GDA_CLIENT_EVENT_TRANSACTION_CANCELLED

   

GdaClientPrivate

typedef struct _GdaClientPrivate GdaClientPrivate;

See Also

GdaConnection.