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

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
Generated by GTK-Doc V1.19