BrowserConnection

## BrowserConnection BrowserConnection — An opened connection |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        BrowserConnectionPrivate;
                        BrowserConnection;
    BrowserConnection * browser_connection_new              (GdaConnection *cnc);
    const gchar *       browser_connection_get_name         (BrowserConnection *bcnc);
    gchar *             browser_connection_get_long_name    (BrowserConnection *bcnc);
    const GdaDsnInfo *  browser_connection_get_information  (BrowserConnection *bcnc);
    gboolean            browser_connection_is_virtual       (BrowserConnection *bcnc);
    gboolean            browser_connection_is_busy          (BrowserConnection *bcnc,
                                                             gchar **out_reason);
    void                browser_connection_update_meta_data (BrowserConnection *bcnc);
    void                browser_connection_meta_data_changed
                                                            (BrowserConnection *bcnc);
    GdaMetaStruct *     browser_connection_get_meta_struct  (BrowserConnection *bcnc);
    GdaMetaStore *      browser_connection_get_meta_store   (BrowserConnection *bcnc);
    const gchar *       browser_connection_get_dictionary_file
                                                            (BrowserConnection *bcnc);
    ToolsFavorites *    browser_connection_get_favorites    (BrowserConnection *bcnc);
    gchar **            browser_connection_get_completions  (BrowserConnection *bcnc,
                                                             const gchar *sql,
                                                             gint start,
                                                             gint end);
    GdaSqlParser *      browser_connection_create_parser    (BrowserConnection *bcnc);
    gchar *             browser_connection_render_pretty_sql
                                                            (BrowserConnection *bcnc,
                                                             GdaStatement *stmt);
    guint               browser_connection_execute_statement
                                                            (BrowserConnection *bcnc,
                                                             GdaStatement *stmt,
                                                             GdaSet *params,
                                                             GdaStatementModelUsage model_usage,
                                                             gboolean need_last_insert_row,
                                                             GError **error);
    GObject *           browser_connection_execution_get_result
                                                            (BrowserConnection *bcnc,
                                                             guint exec_id,
                                                             GdaSet **last_insert_row,
                                                             GError **error);
    void                (*BrowserConnectionExecuteCallback) (BrowserConnection *bcnc,
                                                             guint exec_id,
                                                             GObject *out_result,
                                                             GdaSet *out_last_inserted_row,
                                                             GError *error,
                                                             gpointer data);
    guint               browser_connection_execute_statement_cb
                                                            (BrowserConnection *bcnc,
                                                             GdaStatement *stmt,
                                                             GdaSet *params,
                                                             GdaStatementModelUsage model_usage,
                                                             gboolean need_last_insert_row,
                                                             BrowserConnectionExecuteCallback callback,
                                                             gpointer data,
                                                             GError **error);
    gboolean            browser_connection_normalize_sql_statement
                                                            (BrowserConnection *bcnc,
                                                             GdaSqlStatement *sqlst,
                                                             GError **error);
    gboolean            browser_connection_check_sql_statement_validify
                                                            (BrowserConnection *bcnc,
                                                             GdaSqlStatement *sqlst,
                                                             GError **error);
    guint               browser_connection_rerun_select     (BrowserConnection *bcnc,
                                                             GdaDataModel *model,
                                                             GError **error);
    guint               browser_connection_rerun_select_cb  (BrowserConnection *bcnc,
                                                             GdaDataModel *model,
                                                             BrowserConnectionExecuteCallback callback,
                                                             gpointer data,
                                                             GError **error);

    gboolean            browser_connection_begin            (BrowserConnection *bcnc,
                                                             GError **error);
    gboolean            browser_connection_commit           (BrowserConnection *bcnc,
                                                             GError **error);
    gboolean            browser_connection_rollback         (BrowserConnection *bcnc,
                                                             GError **error);
    GdaTransactionStatus * browser_connection_get_transaction_status
                                                            (BrowserConnection *bcnc);

    gboolean            browser_connection_set_table_column_attribute
                                                            (BrowserConnection *bcnc,
                                                             GdaMetaTable *table,
                                                             GdaMetaTableColumn *column,
                                                             const gchar *attr_name,
                                                             const gchar *value,
                                                             GError **error);
    gchar *             browser_connection_get_table_column_attribute
                                                            (BrowserConnection *bcnc,
                                                             GdaMetaTable *table,
                                                             GdaMetaTableColumn *column,
                                                             const gchar *attr_name,
                                                             GError **error);
    void                browser_connection_define_ui_plugins_for_batch
                                                            (BrowserConnection *bcnc,
                                                             GdaBatch *batch,
                                                             GdaSet *params);
    void                browser_connection_define_ui_plugins_for_stmt
                                                            (BrowserConnection *bcnc,
                                                             GdaStatement *stmt,
                                                             GdaSet *params);

    void                browser_connection_keep_variables   (BrowserConnection *bcnc,
                                                             GdaSet *set);
    void                browser_connection_load_variables   (BrowserConnection *bcnc,
                                                             GdaSet *set);

## Object Hierarchy

      GObject
       +----BrowserConnection

## Properties

      "gda-connection"           GdaConnection*        : Write / Construct Only

## Signals

      "busy"                                           : Run First
      "favorites-changed"                              : Run First
      "meta-changed"                                   : Run First
      "table-column-pref-changed"                      : Run First
      "transaction-status-changed"                     : Run First

## Description

The BrowserConnection object wraps a GdaConnection with some additionnal features. The wrapped GdaConnection is only accessible from within the BrowserConnection object, so to use a connection, you have to use the BrowserConnection's methods.

## Details

### BrowserConnectionPrivate

    typedef struct {
    	GdaThreadWrapper *wrapper;
    	GIOChannel       *ioc;
    	guint             ioc_watch_id;
    	GSList           *wrapper_jobs;
    	guint             wrapper_results_timer;
    	gboolean          long_timer;
    	gint              nb_no_job_waits; /* number of times check_for_wrapper_result() has been
    					      called without any job */

    	GHashTable       *executed_statements; /* key = guint exec ID, value = a StatementResult pointer */

    	gulong            meta_store_signal;
    	gulong            transaction_status_signal;

    	gchar         *name;
    	GdaConnection *cnc;
    	gchar         *dict_file_name;
            GdaSqlParser  *parser;

    	GdaDsnInfo     dsn_info;
    #if GLIB_CHECK_VERSION(2,31,7)
    	GMutex        mstruct_mutex;
    #else
    	GMutex        *p_mstruct_mutex;
    #endif
    	GSList        *p_mstruct_list; /* private GdaMetaStruct list: while they are being created */
    	GdaMetaStruct *c_mstruct; /* last GdaMetaStruct up to date, ready to be passed as @mstruct */
    	GdaMetaStruct *mstruct; /* public GdaMetaStruct: once it has been created and is no more modified */

    	ToolsFavorites *bfav;

    	gboolean  busy;
    	gchar    *busy_reason;

    	GdaConnection *store_cnc;

    	GdaSet        *variables;

    	GSList        *results_list; /* list of #ExecCallbackData pointers */
    	gulong         results_timer_id;
    } BrowserConnectionPrivate;

### BrowserConnection

    typedef struct _BrowserConnection BrowserConnection;

### browser_connection_new ()

    BrowserConnection * browser_connection_new              (GdaConnection *cnc);

Creates a new BrowserConnection object wrapping `cnc`. The `browser_core_take_connection()` method must be called on the new object to mahe it managed by the browser.

To close the new connection, use `browser_core_close_connection()`.

`cnc` : | a GdaConnection
Returns : | a new object

### browser_connection_get_name ()

    const gchar *       browser_connection_get_name         (BrowserConnection *bcnc);

`bcnc` : | a BrowserConnection
Returns : | `bcnc`'s name

### browser_connection_get_long_name ()

    gchar *             browser_connection_get_long_name    (BrowserConnection *bcnc);

Get the "long" name of `bcnc`

`bcnc` : | a BrowserConnection
Returns : | a new string

### browser_connection_get_information ()

    const GdaDsnInfo *  browser_connection_get_information  (BrowserConnection *bcnc);

Get some information about the connection

`bcnc` : | a BrowserConnection
Returns : | a pointer to the associated GdaDsnInfo

### browser_connection_is_virtual ()

    gboolean            browser_connection_is_virtual       (BrowserConnection *bcnc);

Tells if `bcnc` is a virtual connection or not

`bcnc` : | a BrowserConnection
Returns : | `TRUE` if `bcnc` is a virtual connection

### browser_connection_is_busy ()

    gboolean            browser_connection_is_busy          (BrowserConnection *bcnc,
                                                             gchar **out_reason);

Tells if `bcnc` is currently busy or not.

`bcnc` : | a BrowserConnection
`out_reason` : | a pointer to store a copy of the reason `bcnc` is busy (will be set to `NULL` if `bcnc` is not busy), or `NULL`
Returns : | `TRUE` if `bcnc` is busy

### browser_connection_update_meta_data ()

    void                browser_connection_update_meta_data (BrowserConnection *bcnc);

Make `bcnc` update its meta store in the background.

`bcnc` : | a BrowserConnection

### browser_connection_meta_data_changed ()

    void                browser_connection_meta_data_changed
                                                            (BrowserConnection *bcnc);

Call this function if the meta data has been changed directly (ie. for example after declaring or undeclaring a foreign key). This call creates a new GdaMetaStruct internally used.

`bcnc` : | a BrowserConnection

### browser_connection_get_meta_struct ()

    GdaMetaStruct *     browser_connection_get_meta_struct  (BrowserConnection *bcnc);

Get the GdaMetaStruct maintained up to date by `bcnc`.

`bcnc` : | a BrowserConnection
Returns : | a GdaMetaStruct, the caller does not have any reference to it.

### browser_connection_get_meta_store ()

    GdaMetaStore *      browser_connection_get_meta_store   (BrowserConnection *bcnc);

`bcnc` : | a BrowserConnection
Returns : | `bcnc`'s GdaMetaStore, the caller does not have any reference to it.

### browser_connection_get_dictionary_file ()

    const gchar *       browser_connection_get_dictionary_file
                                                            (BrowserConnection *bcnc);

`bcnc` : | a BrowserConnection
Returns : | the dictionary file name used by `bcnc`, or `NULL`

### browser_connection_get_favorites ()

    ToolsFavorites *    browser_connection_get_favorites    (BrowserConnection *bcnc);

Get `bcnc`'s favorites handler

`bcnc` : | a BrowserConnection
Returns : | the ToolsFavorites used by `bcnc`. [transfer none]

### browser_connection_get_completions ()

    gchar **            browser_connection_get_completions  (BrowserConnection *bcnc,
                                                             const gchar *sql,
                                                             gint start,
                                                             gint end);

See `gda_completion_list_get()`

`bcnc` : | a BrowserConnection
Returns : | a new array of strings, or NULL (use `g_strfreev()` to free the returned array)

### browser_connection_create_parser ()

    GdaSqlParser *      browser_connection_create_parser    (BrowserConnection *bcnc);

Get a new GdaSqlParser object for `bcnc`

`bcnc` : | a BrowserConnection
Returns : | a new GdaSqlParser

### browser_connection_render_pretty_sql ()

    gchar *             browser_connection_render_pretty_sql
                                                            (BrowserConnection *bcnc,
                                                             GdaStatement *stmt);

Renders `stmt` as SQL well indented

`bcnc` : | a BrowserConnection
`stmt` : | a GdaStatement
Returns : | a new string

### browser_connection_execute_statement ()

    guint               browser_connection_execute_statement
                                                            (BrowserConnection *bcnc,
                                                             GdaStatement *stmt,
                                                             GdaSet *params,
                                                             GdaStatementModelUsage model_usage,
                                                             gboolean need_last_insert_row,
                                                             GError **error);

Executes `stmt` by `bcnc`. Unless specific requirements, it's easier to use `browser_connection_execute_statement_cb()`.

`bcnc` : | a BrowserConnection
`stmt` : | a GdaStatement
`params` : | a GdaSet as parameters, or `NULL`
`model_usage` : | how the returned data model (if any) will be used
`need_last_insert_row` : | `TRUE` if the values of the last interted row must be computed
`error` : | a place to store errors, or `NULL`
Returns : | a job ID, to be used with `browser_connection_execution_get_result()`, or `0` if an error occurred

### browser_connection_execution_get_result ()

    GObject *           browser_connection_execution_get_result
                                                            (BrowserConnection *bcnc,
                                                             guint exec_id,
                                                             GdaSet **last_insert_row,
                                                             GError **error);

Pick up the result of the `exec_id`'s execution.

`bcnc` : | a BrowserConnection
`exec_id` : | the ID of the excution
`last_insert_row` : | a place to store the last inserted row, if any, or `NULL`
`error` : | a place to store errors, or `NULL`
Returns : | the execution result, or `NULL` if either an error occurred or the result is not yet ready

### BrowserConnectionExecuteCallback ()

    void                (*BrowserConnectionExecuteCallback) (BrowserConnection *bcnc,
                                                             guint exec_id,
                                                             GObject *out_result,
                                                             GdaSet *out_last_inserted_row,
                                                             GError *error,
                                                             gpointer data);

Callback function called by `browser_connection_execute_statement_cb()`. If you need to keep some of the arguments for a later usage, you need to ref/copy them.

None of the passed arguments must not be modified

### browser_connection_execute_statement_cb ()

    guint               browser_connection_execute_statement_cb
                                                            (BrowserConnection *bcnc,
                                                             GdaStatement *stmt,
                                                             GdaSet *params,
                                                             GdaStatementModelUsage model_usage,
                                                             gboolean need_last_insert_row,
                                                             BrowserConnectionExecuteCallback callback,
                                                             gpointer data,
                                                             GError **error);

Executes `stmt` by `bcnc` and calls `callback` when done. This occurs in the UI thread and avoids having to set up a waiting mechanism to call `browser_connection_execution_get_result()` repeatedly.

`bcnc` : | a BrowserConnection
`stmt` : | a GdaStatement
`params` : | a GdaSet as parameters, or `NULL`
`model_usage` : | how the returned data model (if any) will be used
`need_last_insert_row` : | `TRUE` if the values of the last interted row must be computed
`callback` : | the function to call when statement has been executed
`data` : | data to pass to `callback`, or `NULL`
`error` : | a place to store errors, or `NULL`
Returns : | a job ID, or `0` if an error occurred

### browser_connection_normalize_sql_statement ()

    gboolean            browser_connection_normalize_sql_statement
                                                            (BrowserConnection *bcnc,
                                                             GdaSqlStatement *sqlst,
                                                             GError **error);

See `gda_sql_statement_normalize()`.

`bcnc` : | a BrowserConnection
`sqlst` : | a GdaSqlStatement
`error` : | a place to store errors, or `NULL`
Returns : | `TRUE` if no error occurred

### browser_connection_check_sql_statement_validify ()

    gboolean            browser_connection_check_sql_statement_validify
                                                            (BrowserConnection *bcnc,
                                                             GdaSqlStatement *sqlst,
                                                             GError **error);

### browser_connection_rerun_select ()

    guint               browser_connection_rerun_select     (BrowserConnection *bcnc,
                                                             GdaDataModel *model,
                                                             GError **error);

Re-execute `model`

`bcnc` : | a BrowserConnection object
`model` : | a GdaDataModel, which has to ba a GdaDataSelect
`error` : | a place to store errors, or `NULL`
Returns : | a job ID, or `0` if an error occurred

### browser_connection_rerun_select_cb ()

    guint               browser_connection_rerun_select_cb  (BrowserConnection *bcnc,
                                                             GdaDataModel *model,
                                                             BrowserConnectionExecuteCallback callback,
                                                             gpointer data,
                                                             GError **error);

Re-execute `model`.

Warning: `gda_data_model_freeze()` and `gda_data_model_thaw()` should be used before and after this call since the model will signal its changes in a thread which is not the GUI thread.

`bcnc` : | a BrowserConnection object
`model` : | a GdaDataModel, which has to ba a GdaDataSelect
`callback` : | the function to call when statement has been executed
`data` : | data to pass to `callback`, or `NULL`
`error` : | a place to store errors, or `NULL`
Returns : | a job ID, or `0` if an error occurred

### browser_connection_begin ()

    gboolean            browser_connection_begin            (BrowserConnection *bcnc,
                                                             GError **error);

Begins a transaction

`bcnc` : | a BrowserConnection
`error` : | a place to store errors, or `NULL`

### browser_connection_commit ()

    gboolean            browser_connection_commit           (BrowserConnection *bcnc,
                                                             GError **error);

Commits a transaction

`bcnc` : | a BrowserConnection
`error` : | a place to store errors, or `NULL`

### browser_connection_rollback ()

    gboolean            browser_connection_rollback         (BrowserConnection *bcnc,
                                                             GError **error);

Rolls back a transaction

`bcnc` : | a BrowserConnection
`error` : | a place to store errors, or `NULL`

### browser_connection_get_transaction_status ()

    GdaTransactionStatus * browser_connection_get_transaction_status
                                                            (BrowserConnection *bcnc);

Retuns: the GdaTransactionStatus of the connection, or `NULL`

`bcnc` : | a BrowserConnection

### browser_connection_set_table_column_attribute ()

    gboolean            browser_connection_set_table_column_attribute
                                                            (BrowserConnection *bcnc,
                                                             GdaMetaTable *table,
                                                             GdaMetaTableColumn *column,
                                                             const gchar *attr_name,
                                                             const gchar *value,
                                                             GError **error);

`attr_name` : | attribute name, not `NULL`
`value` : | value to set, or `NULL` to unset
Returns : | `TRUE` if no error occurred

### browser_connection_get_table_column_attribute ()

    gchar *             browser_connection_get_table_column_attribute
                                                            (BrowserConnection *bcnc,
                                                             GdaMetaTable *table,
                                                             GdaMetaTableColumn *column,
                                                             const gchar *attr_name,
                                                             GError **error);

`column` : | may be `NULL`
`attr_name` : | attribute name, not `NULL`
Returns : | the requested attribute (as a new string), or `NULL` if not set or if an error occurred

### browser_connection_define_ui_plugins_for_batch ()

    void                browser_connection_define_ui_plugins_for_batch
                                                            (BrowserConnection *bcnc,
                                                             GdaBatch *batch,
                                                             GdaSet *params);

Calls `browser_connection_define_ui_plugins_for_stmt()` for each statement in `batch`

`bcnc` : | a BrowserConnection object
`batch` : | a GdaBatch
`params` : | a GdaSet (usually created with `gda_batch_get_parameters()`)

### browser_connection_define_ui_plugins_for_stmt ()

    void                browser_connection_define_ui_plugins_for_stmt
                                                            (BrowserConnection *bcnc,
                                                             GdaStatement *stmt,
                                                             GdaSet *params);

Analyses `stmt` and assign plugins to each GdaHolder in `params` according to the preferences stored for each table's field, defined at some point using `browser_connection_set_table_column_attribute()`.

`bcnc` : | a BrowserConnection object
`stmt` : | a GdaStatement
`params` : | a GdaSet (usually created with `gda_statement_get_parameters()`)

### browser_connection_keep_variables ()

    void                browser_connection_keep_variables   (BrowserConnection *bcnc,
                                                             GdaSet *set);

Makes a copy of the variables in `set` and keep them in `bcnc`. Retreive them using `browser_connection_load_variables()`

`bcnc` : | a BrowserConnection object
`set` : | a GdaSet containing variables for which a copy has to be done

### browser_connection_load_variables ()

    void                browser_connection_load_variables   (BrowserConnection *bcnc,
                                                             GdaSet *set);

For each GdaHolder in `set`, set the value if one is available in `bcnc`.

`bcnc` : | a BrowserConnection object
`set` : | a GdaSet which will in the end contain (if any) variables stored in `bcnc`

## Property Details

### The `"gda-connection"` property

      "gda-connection"           GdaConnection*        : Write / Construct Only

Connection to use.

## Signal Details

### The `"busy"` signal

    void                user_function                      (BrowserConnection *browserconnection,
                                                            gboolean           arg1,
                                                            gchar             *arg2,
                                                            gpointer           user_data)              : Run First

### The `"favorites-changed"` signal

    void                user_function                      (BrowserConnection *browserconnection,
                                                            gpointer           user_data)              : Run First

### The `"meta-changed"` signal

    void                user_function                      (BrowserConnection *browserconnection,
                                                            GdaMetaStruct     *arg1,
                                                            gpointer           user_data)              : Run First

### The `"table-column-pref-changed"` signal

    void                user_function                      (BrowserConnection *browserconnection,
                                                            gpointer           arg1,
                                                            gpointer           arg2,
                                                            gchar             *arg3,
                                                            gchar             *arg4,
                                                            gpointer           user_data)              : Run First

### The `"transaction-status-changed"` signal

    void                user_function                      (BrowserConnection *browserconnection,
                                                            gpointer           user_data)              : Run First