## GdaConnection GdaConnection — Management of connections to data sources |

## Synopsis

                        GdaConnection;
    enum                GdaConnectionOptions;
    enum                GdaConnectionFeature;
    enum                GdaConnectionSchema;
    GdaConnection*      gda_connection_new                  (GdaClient *client,
                                                             GdaServerProvider *provider,
                                                             const gchar *dsn,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             GdaConnectionOptions 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);
    GdaConnectionOptions 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 *cnc,
                                                             const gchar *username);
    const gchar*        gda_connection_get_username         (GdaConnection *cnc);
    gboolean            gda_connection_set_password         (GdaConnection *cnc,
                                                             const gchar *password);
    const gchar*        gda_connection_get_password         (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);
    gboolean            gda_connection_change_database      (GdaConnection *cnc,
                                                             const gchar *name);
    GdaDataModel*       gda_connection_execute_select_command
                                                            (GdaConnection *cnc,
                                                             GdaCommand *cmd,
                                                             GdaParameterList *params,
                                                             GError **error);
    gint                gda_connection_execute_non_select_command
                                                            (GdaConnection *cnc,
                                                             GdaCommand *cmd,
                                                             GdaParameterList *params,
                                                             GError **error);
    GList*              gda_connection_execute_command      (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,
                                                             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);
    gboolean            gda_connection_supports_feature     (GdaConnection *cnc,
                                                             GdaConnectionFeature feature);
    GdaDataModel*       gda_connection_get_schema           (GdaConnection *cnc,
                                                             GdaConnectionSchema schema,
                                                             GdaParameterList *params,
                                                             GError **error);
    gchar*              gda_connection_value_to_sql_string  (GdaConnection *cnc,
                                                             GValue *from);

## Object Hierarchy

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

## Properties

      "client"                   GdaClient*            : Read / Write
      "cnc-string"               gchar*                : Read / Write
      "dsn"                      gchar*                : Read / Write
      "options"                  GdaConnectionOptions  : Read / Write
      "password"                 gchar*                : Read / Write
      "provider-obj"             GdaServerProvider*    : Read / Write
      "username"                 gchar*                : Read / Write

## Signals

      "conn-closed"                                    : Run First
      "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 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.

## Details

### GdaConnection

    typedef struct _GdaConnection GdaConnection;

### enum GdaConnectionOptions

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

### 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;

### enum GdaConnectionSchema

    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;

### gda_connection_new ()

    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).

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.

### 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_get_client ()

    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.

### 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_infos ()

    GdaServerProviderInfo* gda_connection_get_infos         (GdaConnection *cnc);

### Warning

`gda_connection_get_infos` is deprecated and should not be used in newly-written code.

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 : |

### gda_connection_get_server_version ()

    const gchar*        gda_connection_get_server_version   (GdaConnection *cnc);

### Warning

`gda_connection_get_server_version` is deprecated and should not be used in newly-written code.

Gets the version string of the underlying database server.

`cnc` : | a GdaConnection object.
Returns : | the server version string.

### gda_connection_get_database ()

    const gchar*        gda_connection_get_database         (GdaConnection *cnc);

### Warning

`gda_connection_get_database` is deprecated and should not be used in newly-written code.

Gets the name of the currently active database in the given `GdaConnection`.

`cnc` : | A GdaConnection object.
Returns : | the name of the current database.

### 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_provider ()

    const gchar*        gda_connection_get_provider         (GdaConnection *cnc);

### Warning

`gda_connection_get_provider` is deprecated and should not be used in newly-written code.

Gets the provider id that this connection is connected to.

`cnc` : | a GdaConnection object.
Returns : | the provider ID used to open this connection.

### gda_connection_set_username ()

    gboolean            gda_connection_set_username         (GdaConnection *cnc,
                                                             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.

`cnc` : | a GdaConnection object
`username` : |
Returns : | TRUE on success

### gda_connection_get_username ()

    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.

### gda_connection_set_password ()

    gboolean            gda_connection_set_password         (GdaConnection *cnc,
                                                             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.

`cnc` : | a GdaConnection object
`password` : |
Returns : | TRUE on success

### gda_connection_get_password ()

    const gchar*        gda_connection_get_password         (GdaConnection *cnc);

Gets the password used to open this connection.

`cnc` : | a GdaConnection object.
Returns : | the password.

### 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 (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.
`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.

### gda_connection_change_database ()

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

### Warning

`gda_connection_change_database` is deprecated and should not be used in newly-written code.

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.

### gda_connection_execute_select_command ()

    GdaDataModel*       gda_connection_execute_select_command
                                                            (GdaConnection *cnc,
                                                             GdaCommand *cmd,
                                                             GdaParameterList *params,
                                                             GError **error);

### Warning

`gda_connection_execute_select_command` is deprecated and should not be used in newly-written code.

Executes a selection command on the given connection.

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

Note that no check is made regarding the actual number of statements in `cmd` or if it really contains a SELECT statement. This function is just a convenience function around the `gda_connection_execute_command()` function. If `cmd` contains several statements, the last GdaDataModel is returned.

See the documentation of the `gda_connection_execute_command()` 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, or `NULL` if an error occurred

### gda_connection_execute_non_select_command ()

    gint                gda_connection_execute_non_select_command
                                                            (GdaConnection *cnc,
                                                             GdaCommand *cmd,
                                                             GdaParameterList *params,
                                                             GError **error);

### Warning

`gda_connection_execute_non_select_command` is deprecated and should not be used in newly-written code.

Executes a non-selection command on the given connection.

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

Note that no check is made regarding the actual number of statements in `cmd` or if it really contains a non SELECT statement. This function is just a convenience function around the `gda_connection_execute_command()` function. If `cmd` contains several statements, the last GdaParameterList is returned.

See the documentation of the `gda_connection_execute_command()` 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 : | the number of rows affected (>=0) or -1 or -2

### gda_connection_execute_command ()

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

### Warning

`gda_connection_execute_command` is deprecated and should not be used in newly-written code.

If you know what to expect from `command` (ie if you know it contains a query which will return a data set or a query which will not return a data set) and if `command` contains only one query, then you should use `gda_connection_execute_select_command()` and `gda_connection_execute_non_select_command()` which are easier to use.

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, and GdaParameterList which you are responsible to free when not needed anymore (and unref the data models and parameter lists when they are not used anymore). See the documentation of `gda_server_provider_execute_command()` for more information about the returned list.

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.

- a "ITER_CHUNCK_SIZE" parameter of type G_TYPE_INT which specifies, if "ITER_MODEL_ONLY" is set to TRUE, how many rows are fetched (and cached) from the database everytime the iterator needs to access a row for which the data must be fetched from the database. For the providers which support this setting this parameter to a value greater than one will increase mamory usage but reduce the time spent to transfer data from the database.

`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 and GdaParameterList or `NULL`, as returned by the underlying provider, or `NULL` if an error occurred.

### gda_connection_get_last_insert_id ()

    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.

Beware however that the interpretation and usage of this value depends on the DBMS type being used, , see the limitations of each DBMS for more information.

`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.

### 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 `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.
`name` : | the name of the transation to start
`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
`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
`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_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_get_schema ()

    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, see the `get_schema()` virtual method for providers for more details.

`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 for 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 `"client"` property

      "client"                   GdaClient*            : Read / Write

### The `"cnc-string"` property

      "cnc-string"               gchar*                : Read / Write

Default value: NULL

### The `"dsn"` property

      "dsn"                      gchar*                : Read / Write

Default value: NULL

### The `"options"` property

      "options"                  GdaConnectionOptions  : Read / Write

### The `"password"` property

      "password"                 gchar*                : Read / Write

Default value: NULL

### The `"provider-obj"` property

      "provider-obj"             GdaServerProvider*    : Read / Write

### The `"username"` property

      "username"                 gchar*                : Read / Write

Default value: NULL

## Signal Details

### The `"conn-closed"` 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-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.