GdaConnection

GdaConnection — Management of connections to data sources

Synopsis




                    GdaConnection;
enum                GdaConnectionOptions;
GdaConnection*      gda_connection_open_from_dsn        (const gchar *dsn,
                                                         const gchar *auth_string,
                                                         GdaConnectionOptions options,
                                                         GError **error);
GdaConnection*      gda_connection_open_from_string     (const gchar *provider_name,
                                                         const gchar *cnc_string,
                                                         const gchar *auth_string,
                                                         GdaConnectionOptions options,
                                                         GError **error);
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);

GdaSqlParser*       gda_connection_create_parser        (GdaConnection *cnc);
gchar*              gda_connection_statement_to_sql     (GdaConnection *cnc,
                                                         GdaStatement *stmt,
                                                         GdaSet *params,
                                                         GdaStatementSqlFlag flags,
                                                         GSList **params_used,
                                                         GError **error);
gboolean            gda_connection_statement_prepare    (GdaConnection *cnc,
                                                         GdaStatement *stmt,
                                                         GError **error);
GObject*            gda_connection_statement_execute    (GdaConnection *cnc,
                                                         GdaStatement *stmt,
                                                         GdaSet *params,
                                                         GdaStatementModelUsage model_usage,
                                                         GdaSet **last_insert_row,
                                                         GError **error);
GdaDataModel*       gda_connection_statement_execute_select
                                                        (GdaConnection *cnc,
                                                         GdaStatement *stmt,
                                                         GdaSet *params,
                                                         GError **error);
GdaDataModel*       gda_connection_statement_execute_select_full
                                                        (GdaConnection *cnc,
                                                         GdaStatement *stmt,
                                                         GdaSet *params,
                                                         GdaStatementModelUsage model_usage,
                                                         GType *col_types,
                                                         GError **error);
GdaDataModel*       gda_connection_statement_execute_select_fullv
                                                        (GdaConnection *cnc,
                                                         GdaStatement *stmt,
                                                         GdaSet *params,
                                                         GdaStatementModelUsage model_usage,
                                                         GError **error,
                                                         ...);
gint                gda_connection_statement_execute_non_select
                                                        (GdaConnection *cnc,
                                                         GdaStatement *stmt,
                                                         GdaSet *params,
                                                         GdaSet **last_insert_row,
                                                         GError **error);
gboolean            gda_connection_begin_transaction    (GdaConnection *cnc,
                                                         const gchar *name,
                                                         GdaTransactionIsolation level,
                                                         GError **error);
gboolean            gda_connection_commit_transaction   (GdaConnection *cnc,
                                                         const gchar *name,
                                                         GError **error);
gboolean            gda_connection_rollback_transaction (GdaConnection *cnc,
                                                         const gchar *name,
                                                         GError **error);
gboolean            gda_connection_add_savepoint        (GdaConnection *cnc,
                                                         const gchar *name,
                                                         GError **error);
gboolean            gda_connection_rollback_savepoint   (GdaConnection *cnc,
                                                         const gchar *name,
                                                         GError **error);
gboolean            gda_connection_delete_savepoint     (GdaConnection *cnc,
                                                         const gchar *name,
                                                         GError **error);

GdaTransactionStatus* gda_connection_get_transaction_status
                                                        (GdaConnection *cnc);
GdaConnectionOptions gda_connection_get_options         (GdaConnection *cnc);
GdaServerProvider*  gda_connection_get_provider_obj     (GdaConnection *cnc);
const gchar*        gda_connection_get_provider_name    (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_authentification (GdaConnection *cnc);

void                gda_connection_add_event            (GdaConnection *cnc,
                                                         GdaConnectionEvent *event);
GdaConnectionEvent* 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);

enum                GdaConnectionFeature;
gboolean            gda_connection_supports_feature     (GdaConnection *cnc,
                                                         GdaConnectionFeature feature);
gboolean            gda_connection_update_meta_store    (GdaConnection *cnc,
                                                         GdaMetaContext *context,
                                                         GError **error);
enum                GdaConnectionMetaType;
GdaDataModel*       gda_connection_get_meta_store_data  (GdaConnection *cnc,
                                                         GdaConnectionMetaType meta_type,
                                                         GError **error,
                                                         gint nb_filters,
                                                         ...);
gchar*              gda_connection_value_to_sql_string  (GdaConnection *cnc,
                                                         GValue *from);

Object Hierarchy


  GObject
   +----GdaConnection
         +----GdaVirtualConnection

Properties


  "auth-string"              gchararray            : Read / Write
  "cnc-string"               gchararray            : Read / Write
  "dsn"                      gchararray            : Read / Write
  "meta-store"               GdaMetaStore          : Read / Write
  "options"                  GdaConnectionOptions  : Read / Write
  "provider-obj"             GdaServerProvider     : Read / Write

Signals


  "conn-closed"                                    : Run Last
  "conn-opened"                                    : Run First
  "conn-to-close"                                  : Run First
  "dsn-changed"                                    : Run Last
  "error"                                          : Run Last
  "transaction-status-changed"                     : Run Last

Description

The GdaConnection class offers access to all operations involving an opened connection to a database. GdaConnection objects are not instiated directly but by GdaClient objects using gda_client_open_connection() and gda_client_open_connection_from_string()

Applications can then use GdaConnection objects to execute commands, run transactions, and get information about all objects stored in the underlying database.

Details

GdaConnection

typedef struct _GdaConnection GdaConnection;


enum GdaConnectionOptions

typedef enum {
        GDA_CONNECTION_OPTIONS_NONE = 0,
	GDA_CONNECTION_OPTIONS_READ_ONLY = 1 << 0,
} GdaConnectionOptions;


gda_connection_open_from_dsn ()

GdaConnection*      gda_connection_open_from_dsn        (const gchar *dsn,
                                                         const gchar *auth_string,
                                                         GdaConnectionOptions options,
                                                         GError **error);

This function is the way of opening database connections with libgda.

Establishes a connection to a data source.

The auth_string must contain the authentification information for the server to accept the connection. It is a string containing semi-colon seperated named value, usually like "USERNAME=...;PASSWORD=..." where the ... are replaced by actual values. The actual named parameters required depend on the provider being used, and that list is available as the auth_params member of the GdaProviderInfo struncture for each installed provider (use gda_config_get_provider_info() to get it). Also one can use the "gda-sql-4.0 -L" command to list the possible named parameters.

dsn : data source name.
auth_string : authentification string
options : options for the connection (see GdaConnectionOptions).
error : a place to store an error, or NULL
Returns : a new GdaConnection if connection opening was sucessfull or NULL if there was an error.

gda_connection_open_from_string ()

GdaConnection*      gda_connection_open_from_string     (const gchar *provider_name,
                                                         const gchar *cnc_string,
                                                         const gchar *auth_string,
                                                         GdaConnectionOptions options,
                                                         GError **error);

Opens a connection given a provider ID and a connection string. This allows applications to open connections without having to create a data source in the configuration. The format of cnc_string is similar to PostgreSQL and MySQL connection strings. It is a semicolumn-separated series of key=value pairs. Do not add extra whitespace after the semicolumn separator. The possible keys depend on the provider, the "gda-sql-4.0 -L" command can be used to list the actual keys for each installed database provider.

For example the connection string to open an SQLite connection to a database file named "my_data.db" in the current directory would be "DB_DIR=.;DB_NAME=my_data".

The auth_string must contain the authentification information for the server to accept the connection. It is a string containing semi-colon seperated named value, usually like "USERNAME=...;PASSWORD=..." where the ... are replaced by actual values. The actual named parameters required depend on the provider being used, and that list is available as the auth_params member of the GdaProviderInfo struncture for each installed provider (use gda_config_get_provider_info() to get it). Similarly to the format of the connection string, use the "gda-sql-4.0 -L" command to list the possible named parameters.

Additionnally, it is possible to have the connection string respect the "<provider_name>://<real cnc string>" format, in which case the provider name and the real connection string will be extracted from that string (note that if provider_name is not NULL then it will still be used as the provider ID).

provider_name : provider ID to connect to, or NULL
cnc_string : connection string.
auth_string : authentification string
options : options for the connection (see GdaConnectionOptions).
error : a place to store an error, or NULL
Returns : a new GdaConnection if connection opening was sucessfull or NULL if there was an error.

gda_connection_open ()

gboolean            gda_connection_open                 (GdaConnection *cnc,
                                                         GError **error);

Tries to open the connection.

cnc : a GdaConnection object
error : a place to store errors, or NULL
Returns : TRUE if the connection is opened, and FALSE otherwise.

gda_connection_close ()

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.

gda_connection_close_no_warning ()

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.

gda_connection_is_opened ()

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.

gda_connection_create_parser ()

GdaSqlParser*       gda_connection_create_parser        (GdaConnection *cnc);

Creates a new parser object able to parse the SQL dialect understood by cnc. If the GdaServerProvider object internally used by cnc does not have its own parser, then NULL is returned, and a general SQL parser can be obtained using gda_sql_parser_new().

cnc : a GdaConnection object
Returns : a new GdaSqlParser object

gda_connection_statement_to_sql ()

gchar*              gda_connection_statement_to_sql     (GdaConnection *cnc,
                                                         GdaStatement *stmt,
                                                         GdaSet *params,
                                                         GdaStatementSqlFlag flags,
                                                         GSList **params_used,
                                                         GError **error);

Renders stmt as an SQL statement, adapted to the SQL dialect used by cnc

cnc : a GdaConnection object
stmt : a GdaStatement object
params : a GdaSet object (which can be obtained using gda_statement_get_parameters()), or NULL
flags : SQL rendering flags, as GdaStatementSqlFlag OR'ed values
params_used : a place to store the list of individual GdaHolder objects within params which have been used
error : a place to store errors, or NULL
Returns : a new string, or NULL if an error occurred

gda_connection_statement_prepare ()

gboolean            gda_connection_statement_prepare    (GdaConnection *cnc,
                                                         GdaStatement *stmt,
                                                         GError **error);

Ask the database accessed through the cnc connection to prepare the usage of stmt. This is only usefull if stmt will be used more than once (however some database providers may always prepare stamements before executing them).

This function is also usefull to make sure stmt is fully understood by the database before actually executing it.

Note however that it is also possible that gda_connection_statement_prepare() fails when gda_connection_statement_execute() does not fail (this will usually be the case with statements such as "SELECT * FROM ##tablename::string" because database usually don't allow variables to be used in place of a table name).

cnc : a GdaConnection
stmt : a GdaStatement object
error : a place to store errors, or NULL
Returns : TRUE if no error occurred.

gda_connection_statement_execute ()

GObject*            gda_connection_statement_execute    (GdaConnection *cnc,
                                                         GdaStatement *stmt,
                                                         GdaSet *params,
                                                         GdaStatementModelUsage model_usage,
                                                         GdaSet **last_insert_row,
                                                         GError **error);

Executes stmt. As stmt can, by desing (and if not abused), contain only one SQL statement, the return object will either be:

If last_insert_row is not NULL and stmt is an INSERT statement, then it will contain (if the provider used by cnc supports it) a new GdaSet object composed of value holders named "+<column number>" starting at column 0 which contain the actual inserted values. For example if a table is composed of an 'id' column which is auto incremented and a 'name' column then the execution of a "INSERT INTO mytable (name) VALUES ('joe')" query will return a GdaSet with two holders:

  • one named '+0' which may for example contain 1

  • one named '+1' which will contain 'joe'

See the provider's limitations section for more details about this feature depending on which database is accessed.

cnc : a GdaConnection
stmt : a GdaStatement object
params : a GdaSet object (which can be obtained using gda_statement_get_parameters()), or NULL
model_usage :
last_insert_row : a place to store a new GdaSet object which contains the values of the last inserted row, or NULL
error : a place to store errors, or NULL
Returns : a GObject, or NULL if an error occurred

gda_connection_statement_execute_select ()

GdaDataModel*       gda_connection_statement_execute_select
                                                        (GdaConnection *cnc,
                                                         GdaStatement *stmt,
                                                         GdaSet *params,
                                                         GError **error);

Executes a selection command on the given connection.

This function returns a GdaDataModel resulting from the SELECT statement, or NULL if an error occurred.

This function is just a convenience function around the gda_connection_statement_execute() function.

See the documentation of the gda_connection_statement_execute() for information about the params list of parameters.

cnc : a GdaConnection object.
stmt : a GdaStatement object.
params : a GdaSet object (which can be obtained using gda_statement_get_parameters()), or NULL
error : a place to store an error, or NULL
Returns : a GdaDataModel containing the data returned by the data source, or NULL if an error occurred

gda_connection_statement_execute_select_full ()

GdaDataModel*       gda_connection_statement_execute_select_full
                                                        (GdaConnection *cnc,
                                                         GdaStatement *stmt,
                                                         GdaSet *params,
                                                         GdaStatementModelUsage model_usage,
                                                         GType *col_types,
                                                         GError **error);

Executes a selection command on the given connection.

This function returns a GdaDataModel resulting from the SELECT statement, or NULL if an error occurred.

This function is just a convenience function around the gda_connection_statement_execute() function.

See the documentation of the gda_connection_statement_execute() for information about the params list of parameters.

cnc : a GdaConnection object.
stmt : a GdaStatement object.
params : a GdaSet object (which can be obtained using gda_statement_get_parameters()), or NULL
model_usage : specifies how the returned data model will be used as a GdaStatementModelUsage enum
col_types : an array of GType to request each returned GdaDataModel's column's GType, terminated with the G_TYPE_NONE value. Any value left to 0 will make the database provider determine the real GType. col_types can also be NULL if no column type is specified.
error : a place to store an error, or NULL
Returns : a GdaDataModel containing the data returned by the data source, or NULL if an error occurred

gda_connection_statement_execute_select_fullv ()

GdaDataModel*       gda_connection_statement_execute_select_fullv
                                                        (GdaConnection *cnc,
                                                         GdaStatement *stmt,
                                                         GdaSet *params,
                                                         GdaStatementModelUsage model_usage,
                                                         GError **error,
                                                         ...);

Executes a selection command on the given connection.

This function returns a GdaDataModel resulting from the SELECT statement, or NULL if an error occurred.

This function is just a convenience function around the gda_connection_statement_execute() function.

See the documentation of the gda_connection_statement_execute() for information about the params list of parameters.

cnc : a GdaConnection object.
stmt : a GdaStatement object.
params : a GdaSet object (which can be obtained using gda_statement_get_parameters()), or NULL
model_usage : specifies how the returned data model will be used as a GdaStatementModelUsage enum
error : a place to store an error, or NULL
... : a (-1 terminated) list of (column number, GType) specifying for each column mentionned the GType of the column in the returned GdaDataModel.
Returns : a GdaDataModel containing the data returned by the data source, or NULL if an error occurred

gda_connection_statement_execute_non_select ()

gint                gda_connection_statement_execute_non_select
                                                        (GdaConnection *cnc,
                                                         GdaStatement *stmt,
                                                         GdaSet *params,
                                                         GdaSet **last_insert_row,
                                                         GError **error);

Executes a non-selection statement on the given connection.

This function returns the number of rows affected by the execution of stmt, or -1 if an error occurred, or -2 if the connection's provider does not return the number of rows affected.

This function is just a convenience function around the gda_connection_statement_execute() function. See the documentation of the gda_connection_statement_execute() for information about the params list of parameters.

See gda_connection_statement_execute() form more information about last_insert_row.

cnc : a GdaConnection object.
stmt : a GdaStatement object.
params : a GdaSet object (which can be obtained using gda_statement_get_parameters()), or NULL
last_insert_row : a place to store a new GdaSet object which contains the values of the last inserted row, or NULL
error : a place to store an error, or NULL
Returns : the number of rows affected (>=0) or -1 or -2

gda_connection_begin_transaction ()

gboolean            gda_connection_begin_transaction    (GdaConnection *cnc,
                                                         const gchar *name,
                                                         GdaTransactionIsolation level,
                                                         GError **error);

Starts a transaction on the data source, identified by the name 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.
name : the name of the transation to start, or NULL
level :
error : a place to store errors, or NULL
Returns : TRUE if the transaction was started successfully, FALSE otherwise.

gda_connection_commit_transaction ()

gboolean            gda_connection_commit_transaction   (GdaConnection *cnc,
                                                         const gchar *name,
                                                         GError **error);

Commits the given transaction to the backend database. You need to call gda_connection_begin_transaction() first.

cnc : a GdaConnection object.
name : the name of the transation to commit, or NULL
error : a place to store errors, or NULL
Returns : TRUE if the transaction was finished successfully, FALSE otherwise.

gda_connection_rollback_transaction ()

gboolean            gda_connection_rollback_transaction (GdaConnection *cnc,
                                                         const gchar *name,
                                                         GError **error);

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.
name : the name of the transation to commit, or NULL
error : a place to store errors, or NULL
Returns : TRUE if the operation was successful, FALSE otherwise.

gda_connection_add_savepoint ()

gboolean            gda_connection_add_savepoint        (GdaConnection *cnc,
                                                         const gchar *name,
                                                         GError **error);

Adds a SAVEPOINT named name.

cnc : a GdaConnection object
name : name of the savepoint to add
error : a place to store errors or NULL
Returns : TRUE if no error occurred

gda_connection_rollback_savepoint ()

gboolean            gda_connection_rollback_savepoint   (GdaConnection *cnc,
                                                         const gchar *name,
                                                         GError **error);

Rollback all the modifications made after the SAVEPOINT named name.

cnc : a GdaConnection object
name : name of the savepoint to rollback to
error : a place to store errors or NULL
Returns : TRUE if no error occurred

gda_connection_delete_savepoint ()

gboolean            gda_connection_delete_savepoint     (GdaConnection *cnc,
                                                         const gchar *name,
                                                         GError **error);

Delete the SAVEPOINT named name when not used anymore.

cnc : a GdaConnection object
name : name of the savepoint to delete
error : a place to store errors or NULL
Returns : TRUE if no error occurred

gda_connection_get_transaction_status ()

GdaTransactionStatus* gda_connection_get_transaction_status
                                                        (GdaConnection *cnc);

Get the status of cnc regarding transactions. The returned object should not be modified or destroyed; however it may be modified or destroyed by the connection itself.

If NULL is returned, then no transaction has been associated with cnc

cnc : a GdaConnection object
Returns : a GdaTransactionStatus object, or NULL

gda_connection_get_options ()

GdaConnectionOptions gda_connection_get_options         (GdaConnection *cnc);

Gets the GdaConnectionOptions used to open this connection.

cnc : a GdaConnection object.
Returns : the connection options.

gda_connection_get_provider_obj ()

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)

gda_connection_get_provider_name ()

const gchar*        gda_connection_get_provider_name    (GdaConnection *cnc);

Get the name (identifier) of the database provider used by cnc

cnc : a GdaConnection object
Returns : a non modifiable string

gda_connection_set_dsn ()

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 : a GdaConnection object
datasource : a gda datasource
Returns : TRUE on success

gda_connection_get_dsn ()

const gchar*        gda_connection_get_dsn              (GdaConnection *cnc);

cnc : a GdaConnection object
Returns : the data source name the connection object is connected to.

gda_connection_get_cnc_string ()

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.

gda_connection_get_authentification ()

const gchar*        gda_connection_get_authentification (GdaConnection *cnc);

Gets the user name used to open this connection.

cnc : a GdaConnection object.
Returns : the user name.

gda_connection_add_event ()

void                gda_connection_add_event            (GdaConnection *cnc,
                                                         GdaConnectionEvent *event);

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 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.
event : is stored internally, so you don't need to unref it.

gda_connection_add_event_string ()

GdaConnectionEvent* 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 GdaConnection object.
str : a format string (see the printf(3) documentation).
... : the arguments to insert in the error message.
Returns : a new GdaConnectionEvent object, however the caller does not hold a reference to the returned object, and if need be the caller must call g_object_ref() on it.

gda_connection_add_events_list ()

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.

gda_connection_get_events ()

const GList*        gda_connection_get_events           (GdaConnection *cnc);

Retrieves a list of the last errors occurred during the connection. You can make a copy of the list using gda_connection_event_list_copy.

cnc : a GdaConnection.
Returns : a GList of GdaConnectionEvent.

gda_connection_clear_events_list ()

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.

enum GdaConnectionFeature

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_SAVEPOINTS,
	GDA_CONNECTION_FEATURE_SAVEPOINTS_REMOVE,
	GDA_CONNECTION_FEATURE_TRIGGERS,
	GDA_CONNECTION_FEATURE_UPDATABLE_CURSOR,
	GDA_CONNECTION_FEATURE_USERS,
	GDA_CONNECTION_FEATURE_VIEWS,
	GDA_CONNECTION_FEATURE_XML_QUERIES
} GdaConnectionFeature;


gda_connection_supports_feature ()

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.

gda_connection_update_meta_store ()

gboolean            gda_connection_update_meta_store    (GdaConnection *cnc,
                                                         GdaMetaContext *context,
                                                         GError **error);

Updates cnc's associated GdaMetaStore. If context is not NULL, then only the parts described by context will be updated, and if it is NULL, then the complete meta store will be updated.

cnc : a GdaConnection object.
context : description of which part of cnc's associated GdaMetaStore should be updated, or NULL
error : a place to store errors, or NULL
Returns : TRUE if no error occurred

enum GdaConnectionMetaType

typedef enum {
	GDA_CONNECTION_META_NAMESPACES,
	GDA_CONNECTION_META_TYPES,
	GDA_CONNECTION_META_TABLES,
	GDA_CONNECTION_META_VIEWS,
	GDA_CONNECTION_META_FIELDS
} GdaConnectionMetaType;

GDA_CONNECTION_META_NAMESPACES lists the namespaces (or schemas for PostgreSQL)
GDA_CONNECTION_META_TYPES
GDA_CONNECTION_META_TABLES lists the tables
GDA_CONNECTION_META_VIEWS
GDA_CONNECTION_META_FIELDS

gda_connection_get_meta_store_data ()

GdaDataModel*       gda_connection_get_meta_store_data  (GdaConnection *cnc,
                                                         GdaConnectionMetaType meta_type,
                                                         GError **error,
                                                         gint nb_filters,
                                                         ...);

Retreives data stored in cnc's associated GdaMetaStore object. This method is usefull to easily get some information about the meta-data associated to cnc, such as the list of tables, views, and other database objects.

Note: it's up to the caller to make sure the information contained within cnc's associated GdaMetaStore is up to date using gda_connection_update_meta_store() (it can become outdated if the database's schema is accessed from outside of Libgda).

For more information about the returned data model's attributes, or about the meta_type and @... filter arguments, see this description.

cnc : a GdaConnection object.
meta_type : describes which data to get.
error : a place to store errors, or NULL
nb_filters : the number of filters in the @... argument
... : a list of (filter name (gchar *), filter value (GValue*)) pairs specifying the filter to apply to the returned data model's contents (there must be nb_filters pairs)
Returns : a GdaDataModel containing the data required. The caller is responsible of freeing the returned model using g_object_unref().

gda_connection_value_to_sql_string ()

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.

Property Details

The "auth-string" property

  "auth-string"              gchararray            : Read / Write

Default value: NULL


The "cnc-string" property

  "cnc-string"               gchararray            : Read / Write

Default value: NULL


The "dsn" property

  "dsn"                      gchararray            : Read / Write

Default value: NULL


The "meta-store" property

  "meta-store"               GdaMetaStore          : Read / Write


The "options" property

  "options"                  GdaConnectionOptions  : Read / Write


The "provider-obj" property

  "provider-obj"             GdaServerProvider     : Read / Write

Signal Details

The "conn-closed" signal

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.

The "conn-opened" signal

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.

The "conn-to-close" signal

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.

The "dsn-changed" signal

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.

The "error" signal

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.

The "transaction-status-changed" signal

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.