![]() | ![]() | ![]() | GNOME Data Access manual | ![]() |
---|
struct GdaConnectionPrivate; struct GdaServerProvider; struct GdaClient; enum GdaConnectionOptions; GdaConnection* gda_connection_new (GdaClient *client, GdaServerProvider *provider, const gchar *dsn, const gchar *username, const gchar *password, GdaConnectionOptions options); 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); GdaConnectionOptions gda_connection_get_options (GdaConnection *cnc); const gchar* gda_connection_get_server_version (GdaConnection *cnc); const gchar* gda_connection_get_database (GdaConnection *cnc); 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_change_database (GdaConnection *cnc, const gchar *name); 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); gint gda_connection_execute_non_query (GdaConnection *cnc, GdaCommand *cmd, GdaParameterList *params); 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_create_blob (GdaConnection *cnc, GdaBlob *blob); const GList* gda_connection_get_errors (GdaConnection *cnc); enum GdaConnectionFeature; gboolean gda_connection_supports (GdaConnection *cnc, GdaConnectionFeature feature); enum GdaConnectionSchema; GdaDataModel* gda_connection_get_schema (GdaConnection *cnc, GdaConnectionSchema schema, GdaParameterList *params);
The
Once obtained, applications can use
struct GdaServerProvider { GObject object; GdaServerProviderPrivate *priv; };
typedef enum { GDA_CONNECTION_OPTIONS_READ_ONLY = 1 << 0, GDA_CONNECTION_OPTIONS_DONT_SHARE = 2 << 0 } GdaConnectionOptions;
GdaConnection* gda_connection_new (GdaClient *client, GdaServerProvider *provider, const gchar *dsn, const gchar *username, const gchar *password, GdaConnectionOptions options);
This function creates a new
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 |
gboolean gda_connection_close (GdaConnection *cnc);
Closes the connection to the underlying data source. After calling this
function, you should not use anymore the
cnc : | a |
Returns : | TRUE if successful, FALSE otherwise. |
gboolean gda_connection_is_open (GdaConnection *cnc);
Checks whether a connection is open or not.
cnc : | a |
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 |
Returns : | the client to which the connection belongs to. |
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.
cnc : | a |
client : | a GdaClient object. |
GdaConnectionOptions gda_connection_get_options (GdaConnection *cnc);
Gets the GdaConnectionOptions used to open this connection.
cnc : | a |
Returns : | the connection options. |
const gchar* gda_connection_get_server_version (GdaConnection *cnc);
Gets the version string of the underlying database server.
cnc : | a |
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 |
Returns : | the name of the current database. |
const gchar* gda_connection_get_dsn (GdaConnection *cnc);
cnc : | a |
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 |
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 |
Returns : | the provider ID used to open this connection. |
const gchar* gda_connection_get_username (GdaConnection *cnc);
Gets the user name used to open this connection.
cnc : | a |
Returns : | the user name. |
const gchar* gda_connection_get_password (GdaConnection *cnc);
Gets the password used to open this connection.
cnc : | a |
Returns : | the password. |
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.
error is stored internally, so you don't need to unref it.
cnc : | a |
error : |
|
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
cnc : | a |
str : | a format string (see the printf(3) documentation). |
... : | the arguments to insert in the error message. |
void gda_connection_add_error_list (GdaConnection *cnc, GList *error_list);
This is just another convenience function which lets you add
a list of
error_list is copied to an internal list and freed.
cnc : | a |
error_list : | a list of |
gboolean gda_connection_change_database (GdaConnection *cnc, const gchar *name);
Change sthe current database for the given connection. This operation is not available in all providers.
cnc : | a |
name : | name of database to switch to. |
Returns : | TRUE if successful, FALSE otherwise. |
gboolean gda_connection_create_database (GdaConnection *cnc, const gchar *name);
Creates a new database named name on the given connection.
cnc : | a |
name : | database name. |
Returns : | TRUE if successful, FALSE otherwise. |
gboolean gda_connection_drop_database (GdaConnection *cnc, const gchar *name);
Drops a database from the given connection.
cnc : | a |
name : | database name. |
Returns : | TRUE if successful, FALSE otherwise. |
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
The return value is a GList of GdaDataModel's, which you are responsible to free when not needed anymore.
cnc : | a |
cmd : | a GdaCommand. |
params : | parameter list. |
Returns : | a list of GdaDataModel's, as returned by the underlying provider. |
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.
cnc : | a |
cmd : | a GdaCommand. |
params : | parameter list. |
Returns : | a GdaDataModel containing the data returned by the data source, or NULL on error. |
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.
cnc : | a |
cmd : | a GdaCommand. |
params : | parameter list. |
Returns : | the number of affected rows by the executed command, or -1 on error. |
gboolean gda_connection_begin_transaction (GdaConnection *cnc, GdaTransaction *xaction);
Startq 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.
cnc : | a |
xaction : | a |
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 |
xaction : | a |
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 |
xaction : | a |
Returns : | TRUE if the operation was successful, FALSE otherwise. |
gboolean gda_connection_create_blob (GdaConnection *cnc, GdaBlob *blob);
Creates a BLOB (Binary Large OBject) with read/write access.
cnc : | a |
blob : | a user-allocated GdaBlob structure. |
Returns : | FALSE if the database does not support BLOBs. TRUE otherwise and the GdaBlob is created and ready to be used. |
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.
cnc : | a |
Returns : | a GList of |
typedef enum { GDA_CONNECTION_FEATURE_AGGREGATES, 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, GDA_CONNECTION_FEATURE_BLOBS } GdaConnectionFeature;
gboolean gda_connection_supports (GdaConnection *cnc, GdaConnectionFeature feature);
Asks the underlying provider for if a specific feature is supported.
cnc : | a |
feature : | feature to ask for. |
Returns : | TRUE if the provider supports it, FALSE if not. |
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 } GdaConnectionSchema;
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.
cnc : | a |
schema : | database schema to get. |
params : | parameter list. |
Returns : | a GdaDataModel containing the data required. |
<<< gda-config | GdaDataModelArray >>> |