Top | ![]() |
![]() |
![]() |
![]() |
The GdaConnection class offers access to all operations involving an opened connection to a database. GdaConnection objects are obtained via the GdaClient class.
Once obtained, applications can use GdaConnection to execute commands, run transactions, and get information about all objects stored in the underlying database.
GdaConnection * gda_connection_new (GdaClient *client
,GdaServerProvider *provider
,const gchar *dsn
,const gchar *username
,const gchar *password
,GdaConnectionOptions options
);
This function creates a new GdaConnection object. It is not intended to be used directly by applications (use gda_client_open_connection instead).
client |
a GdaClient object. |
|
provider |
a GdaServerProvider object. |
|
dsn |
GDA data source to connect to. |
|
username |
user name to use to connect. |
|
password |
password for |
|
options |
options for the connection. |
gboolean
gda_connection_close (GdaConnection *cnc
);
Closes 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.
gboolean
gda_connection_is_open (GdaConnection *cnc
);
Checks whether a connection is open or not.
GdaClient *
gda_connection_get_client (GdaConnection *cnc
);
Gets the GdaClient object associated with a connection. This is always the client that created the connection, as returned by gda_client_open_connection.
void gda_connection_set_client (GdaConnection *cnc
,GdaClient *client
);
Associates a GdaClient with this connection. This function is not intended to be called by applications.
GdaConnectionOptions
gda_connection_get_options (GdaConnection *cnc
);
Gets the GdaConnectionOptions used to open this connection.
const gchar *
gda_connection_get_server_version (GdaConnection *cnc
);
Gets the version string of the underlying database server.
const gchar *
gda_connection_get_database (GdaConnection *cnc
);
Gets the name of the currently active database in the given
GdaConnection
.
const gchar *
gda_connection_get_dsn (GdaConnection *cnc
);
Returns the data source name the connection object is connected to.
const gchar *
gda_connection_get_cnc_string (GdaConnection *cnc
);
Gets 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.
const gchar *
gda_connection_get_provider (GdaConnection *cnc
);
Gets the provider id that this connection is connected to.
const gchar *
gda_connection_get_username (GdaConnection *cnc
);
Gets the user name used to open this connection.
const gchar *
gda_connection_get_password (GdaConnection *cnc
);
Gets the password used to open this connection.
void gda_connection_add_error (GdaConnection *cnc
,GdaError *error
);
Adds 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.
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.
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.
error_list
is copied to an internal list and freed.
gboolean gda_connection_change_database (GdaConnection *cnc
,const gchar *name
);
Changes the current database for the given connection. This operation is not available in all providers.
gboolean gda_connection_create_database (GdaConnection *cnc
,const gchar *name
);
Creates a new database named name
on the given connection.
gboolean gda_connection_drop_database (GdaConnection *cnc
,const gchar *name
);
Drops a database from the given connection.
gboolean gda_connection_create_table (GdaConnection *cnc
,const gchar *table_name
,const GdaFieldAttributes *attributes[]
);
Creates a table on the given connection from the specified set of fields.
gboolean gda_connection_drop_table (GdaConnection *cnc
,const gchar *table_name
);
Drops a table from the database.
GList * gda_connection_execute_command (GdaConnection *cnc
,GdaCommand *cmd
,GdaParameterList *params
);
Executes 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.
gchar * gda_connection_get_last_insert_id (GdaConnection *cnc
,GdaDataModel *recset
);
Retrieve from the given GdaConnection the ID of the last inserted row. A connection must be specified, and, optionally, a result set. If not NULL, the underlying provider should try to get the last insert ID for the given result set.
GdaDataModel * gda_connection_execute_single_command (GdaConnection *cnc
,GdaCommand *cmd
,GdaParameterList *params
);
Executes 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.
gint gda_connection_execute_non_query (GdaConnection *cnc
,GdaCommand *cmd
,GdaParameterList *params
);
Executes a single command on the underlying database, and gets the number of rows affected.
gboolean gda_connection_begin_transaction (GdaConnection *cnc
,GdaTransaction *xaction
);
Starts a transaction on the data source, identified by the
xaction
parameter.
Before starting a transaction, you can check whether the underlying provider does support transactions or not by using the gda_connection_supports function.
gboolean gda_connection_commit_transaction (GdaConnection *cnc
,GdaTransaction *xaction
);
Commits the given transaction to the backend database. You need to do
gda_connection_begin_transaction()
first.
gboolean gda_connection_rollback_transaction (GdaConnection *cnc
,GdaTransaction *xaction
);
Rollbacks the given transaction. 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.
gboolean gda_connection_create_blob (GdaConnection *cnc
,GdaBlob *blob
);
Creates a BLOB (Binary Large OBject) with read/write access.
const GList *
gda_connection_get_errors (GdaConnection *cnc
);
Retrieves a list of the last errors ocurred in the connection. You can make a copy of the list using gda_error_list_copy.
gboolean gda_connection_supports (GdaConnection *cnc
,GdaConnectionFeature feature
);
Asks the underlying provider for if a specific feature is supported.
GdaDataModel * gda_connection_get_schema (GdaConnection *cnc
,GdaConnectionSchema schema
,GdaParameterList *params
);
Asks 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.
a GdaDataModel containing the data required. The caller is responsible of freeing the returned model.