![]() |
![]() |
![]() |
GNOME Data Access manual | ![]() |
---|---|---|---|---|
GdaConnection; enum GdaConnectionOptions; enum GdaConnectionFeature; enum GdaConnectionSchema; GdaConnection* gda_connection_new (GdaClient *client, GdaServerProvider *provider, const gchar *dsn, const gchar *username, const gchar *password, guint options); gboolean gda_connection_open (GdaConnection *cnc, GError **error); void gda_connection_close (GdaConnection *cnc); void gda_connection_close_no_warning (GdaConnection *cnc); gboolean gda_connection_is_opened (GdaConnection *cnc); GdaClient* gda_connection_get_client (GdaConnection *cnc); guint gda_connection_get_options (GdaConnection *cnc); GdaServerProvider* gda_connection_get_provider_obj (GdaConnection *cnc); GdaServerProviderInfo* gda_connection_get_infos (GdaConnection *cnc); const gchar* gda_connection_get_server_version (GdaConnection *cnc); const gchar* gda_connection_get_database (GdaConnection *cnc); gboolean gda_connection_set_dsn (GdaConnection *cnc, const gchar *datasource); 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); gboolean gda_connection_set_username (GdaConnection *srv, const gchar *username); const gchar* gda_connection_get_username (GdaConnection *cnc); gboolean gda_connection_set_password (GdaConnection *srv, const gchar *password); const gchar* gda_connection_get_password (GdaConnection *cnc); void gda_connection_add_event (GdaConnection *cnc, GdaConnectionEvent *error); void gda_connection_add_event_string (GdaConnection *cnc, const gchar *str, ...); void gda_connection_add_events_list (GdaConnection *cnc, GList *events_list); const GList* gda_connection_get_events (GdaConnection *cnc); void gda_connection_clear_events_list (GdaConnection *cnc); gboolean gda_connection_change_database (GdaConnection *cnc, const gchar *name); GdaDataModel* gda_connection_execute_command (GdaConnection *cnc, GdaCommand *cmd, GdaParameterList *params, GError **error); GList* gda_connection_execute_command_l (GdaConnection *cnc, GdaCommand *cmd, GdaParameterList *params, GError **error); gchar* gda_connection_get_last_insert_id (GdaConnection *cnc, GdaDataModel *recset); gboolean gda_connection_begin_transaction (GdaConnection *cnc, GdaTransaction *xaction); gboolean gda_connection_commit_transaction (GdaConnection *cnc, GdaTransaction *xaction); gboolean gda_connection_rollback_transaction (GdaConnection *cnc, GdaTransaction *xaction); gboolean gda_connection_supports_feature (GdaConnection *cnc, GdaConnectionFeature feature); GdaDataModel* gda_connection_get_schema (GdaConnection *cnc, GdaConnectionSchema schema, GdaParameterList *params, GError **error); GdaBlob* gda_connection_create_blob (GdaConnection *cnc); GdaBlob* gda_connection_fetch_blob_by_id (GdaConnection *cnc, const gchar *sql_id); gchar* gda_connection_value_to_sql_string (GdaConnection *cnc, GValue *from);
"client" gpointer : Read / Write "cnc-string" gchararray : Read / Write "dsn" gchararray : Read / Write "options" guint : Read / Write "password" gchararray : Read / Write "provider-obj" gpointer : Read / Write "username" gchararray : Read / Write
"conn-closed" void user_function (GdaConnection *gdaconnection, gpointer user_data) : Run first "conn-opened" void user_function (GdaConnection *gdaconnection, gpointer user_data) : Run first "conn-to-close" void user_function (GdaConnection *gdaconnection, gpointer user_data) : Run first "dsn-changed" void user_function (GdaConnection *gdaconnection, gpointer user_data) : Run last "error" void user_function (GdaConnection *gdaconnection, GdaConnectionEvent *arg1, gpointer user_data) : Run last
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.
typedef enum { GDA_CONNECTION_OPTIONS_READ_ONLY = 1 << 0, GDA_CONNECTION_OPTIONS_DONT_SHARE = 2 << 0 } GdaConnectionOptions;
typedef enum { GDA_CONNECTION_FEATURE_AGGREGATES, GDA_CONNECTION_FEATURE_BLOBS, GDA_CONNECTION_FEATURE_INDEXES, GDA_CONNECTION_FEATURE_INHERITANCE, GDA_CONNECTION_FEATURE_NAMESPACES, GDA_CONNECTION_FEATURE_PROCEDURES, GDA_CONNECTION_FEATURE_SEQUENCES, GDA_CONNECTION_FEATURE_SQL, GDA_CONNECTION_FEATURE_TRANSACTIONS, GDA_CONNECTION_FEATURE_TRIGGERS, GDA_CONNECTION_FEATURE_UPDATABLE_CURSOR, GDA_CONNECTION_FEATURE_USERS, GDA_CONNECTION_FEATURE_VIEWS, GDA_CONNECTION_FEATURE_XML_QUERIES } GdaConnectionFeature;
typedef enum { GDA_CONNECTION_SCHEMA_AGGREGATES, GDA_CONNECTION_SCHEMA_DATABASES, GDA_CONNECTION_SCHEMA_FIELDS, GDA_CONNECTION_SCHEMA_INDEXES, GDA_CONNECTION_SCHEMA_LANGUAGES, GDA_CONNECTION_SCHEMA_NAMESPACES, GDA_CONNECTION_SCHEMA_PARENT_TABLES, 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, GDA_CONNECTION_SCHEMA_CONSTRAINTS, GDA_CONNECTION_SCHEMA_TABLE_CONTENTS } GdaConnectionSchema;
GdaConnection* gda_connection_new (GdaClient *client, GdaServerProvider *provider, const gchar *dsn, const gchar *username, const gchar *password, guint options);
This function creates a new GdaConnection object. It is not intended to be used directly by applications (use gda_client_open_connection instead).
The connection is not opened at this stage; use
gda_connection_open()
to open the connection.
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 username .
|
options : |
options for the connection. |
Returns : | a newly allocated GdaConnection object. |
gboolean gda_connection_open (GdaConnection *cnc, GError **error);
Tries to open the connection.
cnc : |
|
error : |
a place to store errors, or NULL
|
Returns : | TRUE if the connection is opened, and FALSE otherwise. |
void gda_connection_close (GdaConnection *cnc);
Closes the connection to the underlying data source, but first emits the "conn_to_close" signal.
cnc : |
a GdaConnection object. |
void gda_connection_close_no_warning (GdaConnection *cnc);
Closes the connection to the underlying data source, without emiting any warning signal.
cnc : |
a GdaConnection object. |
gboolean gda_connection_is_opened (GdaConnection *cnc);
Checks whether a connection is open or not.
cnc : |
a GdaConnection object. |
Returns : | TRUE if the connection is open, FALSE if it's 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.
cnc : |
a GdaConnection object. |
Returns : | the client to which the connection belongs to. |
guint gda_connection_get_options (GdaConnection *cnc);
Gets the GdaConnectionOptions used to open this connection.
cnc : |
a GdaConnection object. |
Returns : | the connection options. |
GdaServerProvider* gda_connection_get_provider_obj (GdaConnection *cnc);
Get a pointer to the GdaServerProvider object used to access the database
cnc : |
a GdaConnection object |
Returns : | the GdaServerProvider (NEVER NULL) |
GdaServerProviderInfo* gda_connection_get_infos (GdaConnection *cnc);
Get a pointer to a GdaServerProviderInfo structure (which must not be modified)
to retreive specific information about the provider used by cnc
.
cnc : |
a GdaConnection object |
Returns : |
const gchar* gda_connection_get_server_version (GdaConnection *cnc);
Gets the version string of the underlying database server.
cnc : |
a GdaConnection object. |
Returns : | the server version string. |
const gchar* gda_connection_get_database (GdaConnection *cnc);
Gets the name of the currently active database in the given
GdaConnection
.
cnc : |
A GdaConnection object. |
Returns : | the name of the current database. |
gboolean gda_connection_set_dsn (GdaConnection *cnc, const gchar *datasource);
Sets the data source of the connection. If the connection is already opened, then no action is performed at all and FALSE is returned.
If the requested datasource does not exist, then nothing is done and FALSE is returned.
cnc : |
|
datasource : |
|
Returns : | TRUE on success |
const gchar* gda_connection_get_dsn (GdaConnection *cnc);
cnc : |
a GdaConnection object |
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.
cnc : |
a GdaConnection object. |
Returns : | the connection string used when opening the connection. |
const gchar* gda_connection_get_provider (GdaConnection *cnc);
Gets the provider id that this connection is connected to.
cnc : |
a GdaConnection object. |
Returns : | the provider ID used to open this connection. |
gboolean gda_connection_set_username (GdaConnection *srv, const gchar *username);
Sets the user name for the connection. If the connection is already opened, then no action is performed at all and FALSE is returned.
srv : |
|
username : |
|
Returns : | TRUE on success |
const gchar* gda_connection_get_username (GdaConnection *cnc);
Gets the user name used to open this connection.
cnc : |
a GdaConnection object. |
Returns : | the user name. |
gboolean gda_connection_set_password (GdaConnection *srv, const gchar *password);
Sets the user password for the connection to the server. If the connection is already opened, then no action is performed at all and FALSE is returned.
srv : |
|
password : |
|
Returns : | TRUE on success |
const gchar* gda_connection_get_password (GdaConnection *cnc);
Gets the password used to open this connection.
cnc : |
a GdaConnection object. |
Returns : | the password. |
void gda_connection_add_event (GdaConnection *cnc, GdaConnectionEvent *error);
Adds an event to the given connection. This function is usually called by providers, to inform clients of events that happened during some operation.
As soon as a provider (or a client, it does not matter) calls this
function with an event
object which is an error,
the connection object (and the associated GdaClient object)
emits the "error" signal, to which clients can connect to be
informed of events.
WARNING: the reference to the event
object is stolen by this function!
cnc : |
a GdaConnection object. |
error : |
void gda_connection_add_event_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 GdaConnectionEvent and then calls gda_server_connection_add_error.
cnc : |
a GdaServerConnection object. |
str : |
a format string (see the printf(3) documentation). |
... : |
the arguments to insert in the error message. |
void gda_connection_add_events_list (GdaConnection *cnc, GList *events_list);
This is just another convenience function which lets you add a list of GdaConnectionEvent's to the given connection.* As with gda_connection_add_event and gda_connection_add_event_string, this function makes the connection object emit the "error" signal for each error event.
events_list
is copied to an internal list and freed.
cnc : |
a GdaConnection object. |
events_list : |
a list of GdaConnectionEvent. |
const GList* gda_connection_get_events (GdaConnection *cnc);
Retrieves a list of the last errors occurred in the connection. You can make a copy of the list using gda_connection_event_list_copy.
cnc : |
a GdaConnection. |
Returns : | a GList of GdaConnectionEvent. |
void gda_connection_clear_events_list (GdaConnection *cnc);
This function lets you clear the list of GdaConnectionEvent's of the given connection.
cnc : |
a GdaConnection object. |
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.
cnc : |
a GdaConnection object. |
name : |
name of database to switch to. |
Returns : | TRUE if successful, FALSE otherwise.
|
GdaDataModel* gda_connection_execute_command (GdaConnection *cnc, GdaCommand *cmd, GdaParameterList *params, GError **error);
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_l()
.
Note that if the cmd
command is composed of several SQL statements, the data model
returned is the one corresponding to the last statement.
See the documentation of the gda_connection_execute_command_l()
for information
about the params
list of parameters.
cnc : |
a GdaConnection object. |
cmd : |
a GdaCommand. |
params : |
parameter list for the command |
error : |
a place to store an error, or NULL
|
Returns : | a GdaDataModel containing the data returned by the
data source, NULL if no data was expected, or GDA_CONNECTION_EXEC_FAILED if an error occurred.
|
GList* gda_connection_execute_command_l (GdaConnection *cnc, GdaCommand *cmd, GdaParameterList *params, GError **error);
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 (and unref the data models when they are not used anymore). Note that some nodes of the returned list may actually not point to a GdaDataModel but may be NULL (which corresponds to a command which did not return a data set, like UPDATE commands).
The params
can contain the following parameters:
a "ITER_MODEL_ONLY" parameter of type G_TYPE_BOOLEAN which, if set to TRUE will preferably return a data model which can be accessed only using an iterator.
cnc : |
a GdaConnection object. |
cmd : |
a GdaCommand. |
params : |
parameter list for the commands |
error : |
a place to store an error, or NULL
|
Returns : | a list of GdaDataModel's, as returned by the underlying
provider, or NULL if an error occurred.
|
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.
cnc : |
a GdaConnection object. |
recset : |
recordset. |
Returns : | a string representing the ID of the last inserted row, or NULL if an error occurred or no row has been inserted. It is the caller's reponsibility to free the returned string. |
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_feature function.
cnc : |
a GdaConnection object. |
xaction : |
a GdaTransaction object. |
Returns : | TRUE if the transaction was started successfully, FALSE
otherwise.
|
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.
cnc : |
a GdaConnection object. |
xaction : |
a GdaTransaction object. |
Returns : | TRUE if the transaction was finished successfully,
FALSE otherwise.
|
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.
cnc : |
a GdaConnection object. |
xaction : |
a GdaTransaction object. |
Returns : | TRUE if the operation was successful, FALSE otherwise.
|
gboolean gda_connection_supports_feature (GdaConnection *cnc, GdaConnectionFeature feature);
Asks the underlying provider for if a specific feature is supported.
cnc : |
a GdaConnection object. |
feature : |
feature to ask for. |
Returns : | TRUE if the provider supports it, FALSE if not.
|
GdaDataModel* gda_connection_get_schema (GdaConnection *cnc, GdaConnectionSchema schema, GdaParameterList *params, GError **error);
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.
cnc : |
a GdaConnection object. |
schema : |
database schema to get. |
params : |
parameter list. |
error : |
a place to store errors, or NULL
|
Returns : | a GdaDataModel containing the data required. The caller is responsible of freeing the returned model. |
GdaBlob* gda_connection_create_blob (GdaConnection *cnc);
Fetch an existing BLOB (Binary Large OBject) using its SQL ID.
cnc : |
a GdaConnection object. |
Returns : | FALSE if the database does not support BLOBs. TRUE otherwise
and the GdaBlob is created and ready to be used.
|
GdaBlob* gda_connection_fetch_blob_by_id (GdaConnection *cnc, const gchar *sql_id);
cnc : |
|
sql_id : |
|
Returns : |
gchar* gda_connection_value_to_sql_string (GdaConnection *cnc, GValue *from);
Produces a fully quoted and escaped string from a GValue
cnc : |
a GdaConnection object. |
from : |
GValue to convert from |
Returns : | escaped and quoted value or NULL if not supported. |
void user_function (GdaConnection *gdaconnection, gpointer user_data) : Run first
gdaconnection : |
the object which received the signal. |
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaConnection *gdaconnection, gpointer user_data) : Run first
gdaconnection : |
the object which received the signal. |
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaConnection *gdaconnection, gpointer user_data) : Run first
gdaconnection : |
the object which received the signal. |
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaConnection *gdaconnection, gpointer user_data) : Run last
gdaconnection : |
the object which received the signal. |
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaConnection *gdaconnection, GdaConnectionEvent *arg1, gpointer user_data) : Run last
gdaconnection : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |