El punto de entrada a toda la arquitectura de libgda está representado por la clase GdaClient, que permite el acceso a los distintos Esta funcionalidad incluye:

Para crear un objeto de la clase GdaClient, se usa la siguiente función:

	  GdaClient *gda_client_new (void);
	

Esta función crea un objeto de la clase GdaClient, que servirá de punto de entrada al resto de operaciones que se pueden realizar con libgda. Y no sólo de punto de entrada, si no que también permite servir de controlador de las acciones que se vayan realizando con los distintos proveedores. Esto incluye la recepción de notificaciones de todos los eventos que se produzcan, tales como apertura de una nueva conexión, ejecución de un comando, etc, así como alguna que otra cosa más, que se detallan a continuación.

Una vez que se ha creado una instancia de GdaClient, el siguiente paso, normalmente, es la apertura de conexiones, que se realiza con la función gda_client_open_connection, que tiene la siguiente forma:

El primer parámetro, al igual que en el resto de librerías de GNOME, es un puntero al objeto sobre el que realizar la acción, en este caso un GdaClient. Los siguientes parámetros, especifican los datos a usar en la conexión. El primero de ellos, dsn, especifica el nombre de la fuente de datos a usar para establecer la conexión, tal y como se explicó en el apartado anterior. Los otros dos, username y password, permiten especificar el nombre de usuario y contraseña a usar en la conexión. En el caso de username, si no es NULL, sustituirá al nombre de usuario especificado al crear la fuente de datos; si es NULL, se usará el especificado en la fuente de datos, si es que se especificó al crearla.

gda_client_open_connection devuelve un nuevo objeto del tipo GdaConnection, que es otra clase disponible en libgda y que, como su nombre indica, permite la gestión de las conexiones abiertas por GdaClient.

Al igual que GdaClient es el punto de entrada para la realización de tareas con las distintas fuentes de datos soportadas en libgda, GdaConnection es el punto de entrada a todas las operaciones disponibles en las conexiones que sean establecidas a través de libgda. Las operaciones disponibles a través de GdaConnection son múltiples e incluyen:

Una parte muy importante del acceso a datos en las aplicaciones es la gestión de los errores que puedan producirse como resultado de las distintas operaciones que se realicen sobre la fuente de datos en cuestión. Todas las funciones de libgda informan de cualquier error que se haya producido, pero la información que ofrecen es mínima (normalmente, simplemente un valor gboolean que especifica si la operación se completó con éxito o no). Por ello, libgda ofrece un sistema paralelo a este para informar con todo detalle de todos los errores que se produzcan. Para conseguir esto, se usa el sistema de señales del Sistema de objetos de GLib.sistema de objetos de GLib.

Todo esto se traduce a que tanto GdaClient como GdaConnection incluyen una señal "error" a la que los clientes pueden conectarse (mediante la función g_signal_connect) para ser informados detalladamente de cualquier error que se produzca. Realmente no es necesario que los clientes se conecten a la señal del GdaClient creado y de cualquier conexión que se establezca, pues la clase GdaClient ya captura todos los errores notificados en cada GdaConnection creado, de forma que sólo es necesario conectarse a la señal "error" de GdaClient.

El manejador de esta señal, para la clase GdaConnection tiene la siguiente forma:

Para la clase GdaClient, en cambio, tiene la siguiente forma:

Las dos funcionan de la misma forma, es decir, reciben una lista de errores (parámetro errors). La única diferencia radica en que el manejador de la señal para GdaClient recibe, además de la conexión en la que se ha producido el error, un puntero al cliente sobre el que se estableció la conexión con el manejador de señal.

Por tanto, en la mayor parte de los casos, la gestión de errores de los programas que hagan uso de libgda se reduce a las siguientes líneas de código:

        g_signal_connect (G_OBJECT (client), "error", error_handler, NULL);
	

Seguido del manejador de señal propiamente dicho, que sería la función error_handler en el código anterior, y que sería declarado de la siguiente forma:

	  void error_handler (GdaClient *client,
                              GdaConnection *cnc,
                              GList *errors,
                              gpointer user_data)
	

El parámetro más interesante de cuantos recibe el manejador de señal es, sin duda alguna, errors, que es una GList de GdaError, que es el tipo de datos usado para contener toda la información referente al error. La gestión de este nuevo tipo de datos se ve mucho mejor con un ejemplo:

void
error_handler (GdaClient *client, GdaConnection *cnc, GList *errors, gpointer user_data)
{
}
	

Como se puede apreciar por lo comentado hasta ahora, la gestión de errores con libgda se realiza de forma asíncrona. Si bien este método es especialmente potente, pues permite separar la ejecución de operaciones de la gestión de los errores producidos en ella, hay ocasiones en las que es preferible el conocer, de manera síncrona, cuáles son los errores producidos. Para ello, se puede hacer uso del valor de retorno de las distintas funciones de libgda, que especifica si la operación se produjo con éxito o no. Esto, junto al uso de la función gda_connection_get_errors permiten la obtención de la información de errores inmediatamente después de la ejecución de cada función. Así, por ejemplo:

	  GdaCommand *cmd;

	  cmd = gda_command_new ("UPDATE table1 SET field1 = 0", GDA_COMMAND_TYPE_SQL, 0);
	  if (gda_connection_execute_non_query (cnc, cmd, NULL) == -1) {
	          const GList *errors = gda_connection_get_errors (cnc);
	          ...
	  }
	

Este código, que ejecuta un comando UPDATE y obtiene el número de filas afectadas por el comando (valor de retorno de gda_connection_execute_non_query) hace exactamente lo que se explicaba en el párrafo anterior. Es decir, obtiene el valor de retorno de la función de libgda (en este caso, gda_connection_execute_non_query), que es -1 en caso de producirse un error. Basado en este valor de retorno, el programa obtiene, si se produjo un error, información sobre cada uno de los errores producidos, esto último, mediante la función gda_connection_get_errors.

Una vez obtenida una conexión a un proveedor de datos, las operaciones más corrientes a realizar con dicha conexión incluyen la ejecución de comandos, como se ha visto brevemente en el apartado anterior.

La base para ejecutar comandos en libgda es, aparte, por supuesto, de la clase GdaConnection (no se pueden ejecutar comandos sin una conexión abierta), es la clase GdaCommand, que ofrece una sencilla forma de crear comandos para su posterior ejecución. Esta clase es especialmente sencilla, y la mayor parte de las veces, simplemente será necesario el uso de una sola función:

Esta función permite crear una instancia de la clase GdaCommand con una serie de valores específicos, para distintos parámetros: