GdaBrowser hacking manual: BrowserConnection

## BrowserConnection BrowserConnection — An opened connection |

## Stability Level

Stable, unless otherwise indicated

## Functions

BrowserConnection * | browser_connection_new ()
const gchar * | browser_connection_get_name ()
gchar * | browser_connection_get_long_name ()
const GdaDsnInfo * | browser_connection_get_information ()
gboolean | browser_connection_is_virtual ()
gboolean | browser_connection_is_busy ()
void | browser_connection_update_meta_data ()
void | browser_connection_meta_data_changed ()
GdaMetaStruct * | browser_connection_get_meta_struct ()
GdaMetaStore * | browser_connection_get_meta_store ()
const gchar * | browser_connection_get_dictionary_file ()
ToolsFavorites * | browser_connection_get_favorites ()
gchar ** | browser_connection_get_completions ()
GdaSqlParser * | browser_connection_create_parser ()
gchar * | browser_connection_render_pretty_sql ()
guint | browser_connection_execute_statement ()
GObject * | browser_connection_execution_get_result ()
void | (*BrowserConnectionExecuteCallback) ()
guint | browser_connection_execute_statement_cb ()
gboolean | browser_connection_normalize_sql_statement ()
gboolean | browser_connection_check_sql_statement_validify ()
guint | browser_connection_rerun_select ()
guint | browser_connection_rerun_select_cb ()
gboolean | browser_connection_begin ()
gboolean | browser_connection_commit ()
gboolean | browser_connection_rollback ()
GdaTransactionStatus * | browser_connection_get_transaction_status ()
gboolean | browser_connection_set_table_column_attribute ()
gchar * | browser_connection_get_table_column_attribute ()
void | browser_connection_define_ui_plugins_for_batch ()
void | browser_connection_define_ui_plugins_for_stmt ()
void | browser_connection_keep_variables ()
void | browser_connection_load_variables ()

## Properties

GdaConnection * | gda-connection | Write / Construct Only

## Signals

void | busy | Run First
void | favorites-changed | Run First
void | meta-changed | Run First
void | table-column-pref-changed | Run First
void | transaction-status-changed | Run First

## Types and Values

| BrowserConnectionPrivate
| BrowserConnection

## Object Hierarchy

        GObject
        ╰── BrowserConnection

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

## Functions

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

#### Parameters

cnc | a GdaConnection |

#### Returns

a new object

### browser_connection_get_name ()

    const gchar *
    browser_connection_get_name (BrowserConnection *bcnc);

#### Parameters

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`

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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()`

#### Parameters

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`

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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`

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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`

#### Parameters

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

#### Parameters

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

#### Parameters

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`

#### Parameters

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

#### Parameters

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()`

#### Parameters

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

#### Parameters

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

## Types and Values

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

## Property Details

### The `“gda-connection”` property

      “gda-connection”           GdaConnection *

Connection to use.

Flags: Write / Construct Only

## Signal Details

### The `“busy”` signal

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

Flags: Run First

### The `“favorites-changed”` signal

    void
    user_function (BrowserConnection *browserconnection,
                   gpointer           user_data)

Flags: Run First

### The `“meta-changed”` signal

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

Flags: Run First

### The `“table-column-pref-changed”` signal

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

Flags: Run First

### The `“transaction-status-changed”` signal

    void
    user_function (BrowserConnection *browserconnection,
                   gpointer           user_data)

Flags: Run First