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;

enum GdaClientSpecsType

typedef enum {
	GDA_CLIENT_SPECS_CREATE_DATABASE,
	GDA_CLIENT_SPECS_DROP_DATABASE
} GdaClientSpecsType;

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.

gda_client_open_connection ()

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.

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

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.

gda_client_close_all_connections ()

void        gda_client_close_all_connections
                                            (GdaClient *client);

Closes all connections opened by the given GdaClient object.

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.

gda_client_get_provider_specs ()

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

gda_client_create_database ()

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 <ul> <li>an opened GdaConnection object, named "cnc"</li> <li>the name of the database to create, named "dbname"</li> </ul>

gda_client_drop_database ()

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 <ul> <li>an opened GdaConnection object, named "cnc"</li> <li>the name of the database to destroy, named "dbname"</li> </ul>

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

The "event-notification" signal

void        user_function                  (GdaClient *gdaclient,
                                            gpointer arg1,
                                            gint arg2,
                                            gpointer arg3,
                                            gpointer user_data);