GdaConnection

Name

GdaConnection -- Management of connections to data sources

Synopsis



struct      GdaServerProvider;
struct      GdaConnectionPrivate;
struct      GdaClient;
GdaConnection* gda_connection_new           (GdaClient *client,
                                             GdaServerProvider *provider,
                                             const gchar *dsn,
                                             const gchar *username,
                                             const gchar *password);
gboolean    gda_connection_close            (GdaConnection *cnc);
gboolean    gda_connection_is_open          (GdaConnection *cnc);
GdaClient*  gda_connection_get_client       (GdaConnection *cnc);
void        gda_connection_set_client       (GdaConnection *cnc,
                                             GdaClient *client);
const gchar* gda_connection_get_dsn         (GdaConnection *cnc);
const gchar* gda_connection_get_cnc_string  (GdaConnection *cnc);
const gchar* gda_connection_get_provider    (GdaConnection *cnc);
const gchar* gda_connection_get_username    (GdaConnection *cnc);
const gchar* gda_connection_get_password    (GdaConnection *cnc);
void        gda_connection_add_error        (GdaConnection *cnc,
                                             GdaError *error);
void        gda_connection_add_error_string (GdaConnection *cnc,
                                             const gchar *str,
                                             ...);
void        gda_connection_add_error_list   (GdaConnection *cnc,
                                             GList *error_list);
gboolean    gda_connection_create_database  (GdaConnection *cnc,
                                             const gchar *name);
gboolean    gda_connection_drop_database    (GdaConnection *cnc,
                                             const gchar *name);
GList*      gda_connection_execute_command  (GdaConnection *cnc,
                                             GdaCommand *cmd,
                                             GdaParameterList *params);
GdaDataModel* gda_connection_execute_single_command
                                            (GdaConnection *cnc,
                                             GdaCommand *cmd,
                                             GdaParameterList *params);
gboolean    gda_connection_begin_transaction
                                            (GdaConnection *cnc,
                                             const gchar *id);
gboolean    gda_connection_commit_transaction
                                            (GdaConnection *cnc,
                                             const gchar *id);
gboolean    gda_connection_rollback_transaction
                                            (GdaConnection *cnc,
                                             const gchar *id);
enum        GdaConnectionFeature;
gboolean    gda_connection_supports         (GdaConnection *cnc,
                                             GdaConnectionFeature feature);
enum        GdaConnectionSchema;
GdaDataModel* gda_connection_get_schema     (GdaConnection *cnc,
                                             GdaConnectionSchema schema,
                                             GdaParameterList *params);

Description

Details

struct GdaServerProvider

struct GdaServerProvider {
	GObject object;
	GdaServerProviderPrivate *priv;
};


struct GdaConnectionPrivate

struct GdaConnectionPrivate;


struct GdaClient

struct GdaClient {
	GObject object;
	GdaClientPrivate *priv;
};


gda_connection_new ()

GdaConnection* gda_connection_new           (GdaClient *client,
                                             GdaServerProvider *provider,
                                             const gchar *dsn,
                                             const gchar *username,
                                             const gchar *password);

This function creates a new GdaConnection object. It is not intended to be used directly by applications (use gda_client_open_connection instead).


gda_connection_close ()

gboolean    gda_connection_close            (GdaConnection *cnc);

Close the connection to the underlying data source. After calling this function, you should not use anymore the GdaConnection object, since it may have been destroyed.


gda_connection_is_open ()

gboolean    gda_connection_is_open          (GdaConnection *cnc);

Check whether a connection is open or not.


gda_connection_get_client ()

GdaClient*  gda_connection_get_client       (GdaConnection *cnc);

Get the GdaClient object associated with a connection. This is always the client that created the connection, as returned by gda_client_open_connection.


gda_connection_set_client ()

void        gda_connection_set_client       (GdaConnection *cnc,
                                             GdaClient *client);

Associate a GdaClient with this connection. This function is not intended to be called by applications.


gda_connection_get_dsn ()

const gchar* gda_connection_get_dsn         (GdaConnection *cnc);


gda_connection_get_cnc_string ()

const gchar* gda_connection_get_cnc_string  (GdaConnection *cnc);

Get the connection string used to open this connection.

The connection string is the string sent over to the underlying database provider, which describes the parameters to be used to open a connection on the underlying data source.


gda_connection_get_provider ()

const gchar* gda_connection_get_provider    (GdaConnection *cnc);

Get the provider id that this connection is connected to.


gda_connection_get_username ()

const gchar* gda_connection_get_username    (GdaConnection *cnc);

Get the user name used to open this connection.


gda_connection_get_password ()

const gchar* gda_connection_get_password    (GdaConnection *cnc);

Get the password used to open this connection.


gda_connection_add_error ()

void        gda_connection_add_error        (GdaConnection *cnc,
                                             GdaError *error);

Add an error to the given connection. This function is usually called by providers, to inform clients of errors that happened during some operation.

As soon as a provider (or a client, it does not matter) calls this function, the connection object (and the associated GdaClient object) emits the "error" signal, to which clients can connect to be informed of errors.


gda_connection_add_error_string ()

void        gda_connection_add_error_string (GdaConnection *cnc,
                                             const gchar *str,
                                             ...);

Adds a new error to the given connection object. This is just a convenience function that simply creates a GdaError and then calls gda_server_connection_add_error.


gda_connection_add_error_list ()

void        gda_connection_add_error_list   (GdaConnection *cnc,
                                             GList *error_list);

This is just another convenience function which lets you add a list of GdaError's to the given connection. As with gda_connection_add_error and gda_connection_add_error_string, this function makes the connection object emit the "error" signal. The only difference is that, instead of a notification for each error, this function only does one notification for the whole list of errors.


gda_connection_create_database ()

gboolean    gda_connection_create_database  (GdaConnection *cnc,
                                             const gchar *name);

Create a new database named name on the given connection.


gda_connection_drop_database ()

gboolean    gda_connection_drop_database    (GdaConnection *cnc,
                                             const gchar *name);

Drop a database from the given connection.


gda_connection_execute_command ()

GList*      gda_connection_execute_command  (GdaConnection *cnc,
                                             GdaCommand *cmd,
                                             GdaParameterList *params);

Execute a command on the underlying data source.

This function provides the way to send several commands at once to the data source being accessed by the given GdaConnection object. The GdaCommand specified can contain a list of commands in its "text" property (usually a set of SQL commands separated by ';').

The return value is a GList of GdaDataModel's, which you are responsible to free when not needed anymore.


gda_connection_execute_single_command ()

GdaDataModel* gda_connection_execute_single_command
                                            (GdaConnection *cnc,
                                             GdaCommand *cmd,
                                             GdaParameterList *params);

Execute a single command on the given connection.

This function lets you retrieve a simple data model from the underlying difference, instead of having to retrieve a list of them, as is the case with gda_connection_execute_command.


gda_connection_begin_transaction ()

gboolean    gda_connection_begin_transaction
                                            (GdaConnection *cnc,
                                             const gchar *id);

Start a transaction on the data source, identified by the id parameter, which, if not NULL, will be used by the underlying provider to start a named transaction, if the data source it is connected to does support that concept.

Before starting a transaction, you can check whether the underlying provider does support transactions or not by using the gda_connection_supports function.


gda_connection_commit_transaction ()

gboolean    gda_connection_commit_transaction
                                            (GdaConnection *cnc,
                                             const gchar *id);

Commit the current transaction (if id is NULL) or the named transaction specified by the id parameter.


gda_connection_rollback_transaction ()

gboolean    gda_connection_rollback_transaction
                                            (GdaConnection *cnc,
                                             const gchar *id);

Rollback the current transaction (if id is NULL) or the named transaction specified by the id parameter. This means that all changes made to the underlying data source since the last call to gda_connection_begin_transaction or gda_connection_commit_transaction will be discarded.


enum GdaConnectionFeature

typedef enum {
	GDA_CONNECTION_FEATURE_AGGREGATES,
	GDA_CONNECTION_FEATURE_INDEXES,
	GDA_CONNECTION_FEATURE_PROCEDURES,
	GDA_CONNECTION_FEATURE_SEQUENCES,
	GDA_CONNECTION_FEATURE_SQL,
	GDA_CONNECTION_FEATURE_TRANSACTIONS,
	GDA_CONNECTION_FEATURE_TRIGGERS,
	GDA_CONNECTION_FEATURE_USERS,
	GDA_CONNECTION_FEATURE_VIEWS,
	GDA_CONNECTION_FEATURE_XML_QUERIES
} GdaConnectionFeature;


gda_connection_supports ()

gboolean    gda_connection_supports         (GdaConnection *cnc,
                                             GdaConnectionFeature feature);

Ask the underlying provider for a specific supported feature.


enum GdaConnectionSchema

typedef enum {
	GDA_CONNECTION_SCHEMA_AGGREGATES,
	GDA_CONNECTION_SCHEMA_DATABASES,
	GDA_CONNECTION_SCHEMA_FIELDS,
	GDA_CONNECTION_SCHEMA_INDEXES,
	GDA_CONNECTION_SCHEMA_PROCEDURES,
	GDA_CONNECTION_SCHEMA_SEQUENCES,
	GDA_CONNECTION_SCHEMA_TABLES,
	GDA_CONNECTION_SCHEMA_TRIGGERS,
	GDA_CONNECTION_SCHEMA_TYPES,
	GDA_CONNECTION_SCHEMA_USERS,
	GDA_CONNECTION_SCHEMA_VIEWS
} GdaConnectionSchema;


gda_connection_get_schema ()

GdaDataModel* gda_connection_get_schema     (GdaConnection *cnc,
                                             GdaConnectionSchema schema,
                                             GdaParameterList *params);

Ask the underlying data source for a list of database objects.

This is the function that lets applications ask the different providers about all their database objects (tables, views, procedures, etc). The set of database objects that are retrieved are given by the 2 parameters of this function: schema, which specifies the specific schema required, and params, which is a list of parameters that can be used to give more detail about the objects to be returned.

The list of parameters is specific to each schema type.