Misc API

## Misc API Misc API — Methods dedicated to implementing providers |

## Synopsis

    GdaServerOperation * gda_server_operation_new           (GdaServerOperationType op_type,
                                                             const gchar *xml_file);
    GdaSqlParser *      gda_server_provider_internal_get_parser
                                                            (GdaServerProvider *prov);

    gboolean            gda_server_provider_perform_operation_default
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaServerOperation *op,
                                                             GError **error);
    GdaDataHandler *    gda_server_provider_get_data_handler_default
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GType type,
                                                             const gchar *dbms_type);

    GdaDataHandler *    gda_server_provider_handler_find    (GdaServerProvider *prov,
                                                             GdaConnection *cnc,
                                                             GType g_type,
                                                             const gchar *dbms_type);
    void                gda_server_provider_handler_declare (GdaServerProvider *prov,
                                                             GdaDataHandler *dh,
                                                             GdaConnection *cnc,
                                                             GType g_type,
                                                             const gchar *dbms_type);

    gchar *             gda_server_provider_find_file       (GdaServerProvider *prov,
                                                             const gchar *inst_dir,
                                                             const gchar *filename);
    gchar *             gda_server_provider_load_file_contents
                                                            (const gchar *inst_dir,
                                                             const gchar *data_dir,
                                                             const gchar *filename);

    void                gda_connection_internal_set_provider_data
                                                            (GdaConnection *cnc,
                                                             gpointer data,
                                                             GDestroyNotify destroy_func);
    gpointer            gda_connection_internal_get_provider_data
                                                            (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_clear_events_list    (GdaConnection *cnc);
    GdaConnectionEvent * gda_connection_event_new           (GdaConnectionEventType type);
    void                gda_connection_event_set_event_type (GdaConnectionEvent *event,
                                                             GdaConnectionEventType type);
    void                gda_connection_event_set_description
                                                            (GdaConnectionEvent *event,
                                                             const gchar *description);
    void                gda_connection_event_set_code       (GdaConnectionEvent *event,
                                                             glong code);
    void                gda_connection_event_set_gda_code   (GdaConnectionEvent *event,
                                                             GdaConnectionEventCode code);
    void                gda_connection_event_set_source     (GdaConnectionEvent *event,
                                                             const gchar *source);
    void                gda_connection_event_set_sqlstate   (GdaConnectionEvent *event,
                                                             const gchar *sqlstate);

    void                gda_connection_add_prepared_statement
                                                            (GdaConnection *cnc,
                                                             GdaStatement *gda_stmt,
                                                             GdaPStmt *prepared_stmt);
    void                gda_connection_del_prepared_statement
                                                            (GdaConnection *cnc,
                                                             GdaStatement *gda_stmt);
    GdaPStmt *          gda_connection_get_prepared_statement
                                                            (GdaConnection *cnc,
                                                             GdaStatement *gda_stmt);

    void                gda_connection_internal_transaction_started
                                                            (GdaConnection *cnc,
                                                             const gchar *parent_trans,
                                                             const gchar *trans_name,
                                                             GdaTransactionIsolation isol_level);
    void                gda_connection_internal_transaction_rolledback
                                                            (GdaConnection *cnc,
                                                             const gchar *trans_name);
    void                gda_connection_internal_transaction_committed
                                                            (GdaConnection *cnc,
                                                             const gchar *trans_name);
    void                gda_connection_internal_statement_executed
                                                            (GdaConnection *cnc,
                                                             GdaStatement *stmt,
                                                             GdaSet *params,
                                                             GdaConnectionEvent *error);
    void                gda_connection_internal_savepoint_added
                                                            (GdaConnection *cnc,
                                                             const gchar *parent_trans,
                                                             const gchar *svp_name);
    void                gda_connection_internal_savepoint_rolledback
                                                            (GdaConnection *cnc,
                                                             const gchar *svp_name);
    void                gda_connection_internal_savepoint_removed
                                                            (GdaConnection *cnc,
                                                             const gchar *svp_name);
    void                gda_connection_internal_change_transaction_state
                                                            (GdaConnection *cnc,
                                                             GdaTransactionStatusState newstate);

    gboolean            gda_meta_store_modify               (GdaMetaStore *store,
                                                             const gchar *table_name,
                                                             GdaDataModel *new_data,
                                                             const gchar *condition,
                                                             GError **error,
                                                             ...);
    gboolean            gda_meta_store_modify_with_context  (GdaMetaStore *store,
                                                             GdaMetaContext *context,
                                                             GdaDataModel *new_data,
                                                             GError **error);

    gboolean            gda_compute_dml_statements          (GdaConnection *cnc,
                                                             GdaStatement *select_stmt,
                                                             gboolean require_pk,
                                                             GdaStatement **insert_stmt,
                                                             GdaStatement **update_stmt,
                                                             GdaStatement **delete_stmt,
                                                             GError **error);
    GdaSqlStatement *   gda_compute_select_statement_from_update
                                                            (GdaStatement *update_stmt,
                                                             GError **error);
    GdaSqlExpr *        gda_compute_unique_table_row_condition
                                                            (GdaSqlStatementSelect *stsel,
                                                             GdaMetaTable *mtable,
                                                             gboolean require_pk,
                                                             GError **error);

    gboolean            gda_sql_any_part_check_structure    (GdaSqlAnyPart *node,
                                                             GError **error);

## Description

The methods mentionned in this section are reserved for database providers implementatins and should not bu used by developers outside that scope.

## Details

### gda_server_operation_new ()

    GdaServerOperation * gda_server_operation_new           (GdaServerOperationType op_type,
                                                             const gchar *xml_file);

IMPORTANT NOTE: Using this funtion is not the recommended way of creating a GdaServerOperation object, the correct way is to use `gda_server_provider_create_operation()`; this method is reserved for the database provider's implementation.

Creates a new GdaServerOperation object from the `xml_file` specifications

The `xml_file` must respect the DTD described in the "libgda-server-operation.dtd" file: its top node must be a <serv_op> tag.

`op_type` : | type of operation
`xml_file` : | a file which has the specifications for the GdaServerOperation object to create
Returns : | a new GdaServerOperation object

### gda_server_provider_internal_get_parser ()

    GdaSqlParser *      gda_server_provider_internal_get_parser
                                                            (GdaServerProvider *prov);

This is a factory method to get a unique instance of a GdaSqlParser object for each GdaServerProvider object Don't `unref()` it.

`prov` : | a GdaServerProvider
Returns : | a GdaSqlParser

### gda_server_provider_perform_operation_default ()

    gboolean            gda_server_provider_perform_operation_default
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaServerOperation *op,
                                                             GError **error);

Performs the operation described by `op`, using the SQL from the rendering of the operation

`provider` : | a GdaServerProvider object
`cnc` : | a GdaConnection object which will be used to perform an action, or `NULL`
`op` : | a GdaServerOperation object
`error` : | a place to store an error, or `NULL`
Returns : | TRUE if no error occurred

### gda_server_provider_get_data_handler_default ()

    GdaDataHandler *    gda_server_provider_get_data_handler_default
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GType type,
                                                             const gchar *dbms_type);

Provides the implementation when the default Libgda's data handlers must be used

`provider` : | a server provider.
`cnc` : | a GdaConnection object, or `NULL`
`type` : | a GType
`dbms_type` : | a DBMS type definition
Returns : | a GdaDataHandler, or `NULL`

### gda_server_provider_handler_find ()

    GdaDataHandler *    gda_server_provider_handler_find    (GdaServerProvider *prov,
                                                             GdaConnection *cnc,
                                                             GType g_type,
                                                             const gchar *dbms_type);

`prov` : |
`cnc` : |
`g_type` : |
`dbms_type` : |
Returns : |

### gda_server_provider_handler_declare ()

    void                gda_server_provider_handler_declare (GdaServerProvider *prov,
                                                             GdaDataHandler *dh,
                                                             GdaConnection *cnc,
                                                             GType g_type,
                                                             const gchar *dbms_type);

`prov` : |
`dh` : |
`cnc` : |
`g_type` : |
`dbms_type` : |

### gda_server_provider_find_file ()

    gchar *             gda_server_provider_find_file       (GdaServerProvider *prov,
                                                             const gchar *inst_dir,
                                                             const gchar *filename);

Finds the location of a `filename`. This function should only be used by database provider's implementations

`prov` : | a GdaServerProvider
`inst_dir` : | directory where `prov` is installed
`filename` : | name of the file to find
Returns : | the complete path to `filename`, or `NULL` if not found

### gda_server_provider_load_file_contents ()

    gchar *             gda_server_provider_load_file_contents
                                                            (const gchar *inst_dir,
                                                             const gchar *data_dir,
                                                             const gchar *filename);

Loads and returns the contents of `filename`, which is searched in several places This function should only be used by database provider's implementations

`inst_dir` : | directory where the database provider has been installed
`data_dir` : | DATA directory to look for ($prefix/share)
`filename` : | name of the file to load
Returns : | a new string containing `filename`'s contents, or `NULL` if not found or if an error occurred

### gda_connection_internal_set_provider_data ()

    void                gda_connection_internal_set_provider_data
                                                            (GdaConnection *cnc,
                                                             gpointer data,
                                                             GDestroyNotify destroy_func);

Note: calling this function more than once will not make it call `destroy_func` on any previously set opaque `data`, you'll have to do it yourself.

`cnc` : | a GdaConnection object
`data` : | an opaque structure, known only to the provider for which `cnc` is opened
`destroy_func` : | function to call when the connection closes and `data` needs to be destroyed

### gda_connection_internal_get_provider_data ()

    gpointer            gda_connection_internal_get_provider_data
                                                            (GdaConnection *cnc);

Get the opaque pointer previously set using `gda_connection_internal_set_provider_data()`. If it's not set, then add a connection event and returns `NULL`

`cnc` : | a GdaConnection object
Returns : | the pointer to the opaque structure set using `gda_connection_internal_set_provider_data()`

### gda_connection_add_event ()

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

Adds an event to the given connection. This function is usually called by providers, to inform clients of events that happened during some operation.

As soon as a provider (or a client, it does not matter) calls this function with an `event` object which is an error, the connection object emits the "error" signal, to which clients can connect to be informed of events.

WARNING: the reference to the `event` object is stolen by this function!

`cnc` : | a GdaConnection object.
`event` : | is stored internally, so you don't need to unref it.

### gda_connection_add_event_string ()

    GdaConnectionEvent * gda_connection_add_event_string    (GdaConnection *cnc,
                                                             const gchar *str,
                                                             ...);

Adds a new error to the given connection object. This is just a convenience function that simply creates a GdaConnectionEvent and then calls gda_server_connection_add_error.

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

### gda_connection_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_event_new ()

    GdaConnectionEvent * gda_connection_event_new           (GdaConnectionEventType type);

Creates a new unitialized event object. This class is used for communicating events from the different providers to the clients.

`type` : | the type of event
Returns : | the event object.

### gda_connection_event_set_event_type ()

    void                gda_connection_event_set_event_type (GdaConnectionEvent *event,
                                                             GdaConnectionEventType type);

Sets `event`'s severity (from a simple notice to a fatal event) This function should not be called directly.

`event` : | a GdaConnectionEvent object
`type` : | the severity of the event

### gda_connection_event_set_description ()

    void                gda_connection_event_set_description
                                                            (GdaConnectionEvent *event,
                                                             const gchar *description);

Sets `event`'s `description`. This function should not be called directly.

`event` : | a GdaConnectionEvent.
`description` : | a description.

### gda_connection_event_set_code ()

    void                gda_connection_event_set_code       (GdaConnectionEvent *event,
                                                             glong code);

Sets `event`'s code: the code is specific to the provider being used. If you want to have a common understanding of the event codes, use `gda_connection_event_get_gda_code()` instead.

This function should not be called directly

`event` : | a GdaConnectionEvent.
`code` : | a code.

### gda_connection_event_set_gda_code ()

    void                gda_connection_event_set_gda_code   (GdaConnectionEvent *event,
                                                             GdaConnectionEventCode code);

Sets `event`'s gda code: that code is standardized by the libgda library. If you want to specify the corresponding provider specific code, use `gda_connection_event_get_code()` or `gda_connection_event_get_sqlstate()` instead.

This function should not be called directly

`event` : | a GdaConnectionEvent
`code` : | a code

### gda_connection_event_set_source ()

    void                gda_connection_event_set_source     (GdaConnectionEvent *event,
                                                             const gchar *source);

Sets `event`'s `source`; this function should not be called directly

`event` : | a GdaConnectionEvent.
`source` : | a source.

### gda_connection_event_set_sqlstate ()

    void                gda_connection_event_set_sqlstate   (GdaConnectionEvent *event,
                                                             const gchar *sqlstate);

Changes the SQLSTATE code of `event`, this function should not be called directly

Sets `event`'s SQL state.

`event` : | a GdaConnectionEvent.
`sqlstate` : | SQL state.

### gda_connection_add_prepared_statement ()

    void                gda_connection_add_prepared_statement
                                                            (GdaConnection *cnc,
                                                             GdaStatement *gda_stmt,
                                                             GdaPStmt *prepared_stmt);

Declares that `prepared_stmt` is a prepared statement object associated to `gda_stmt` within the connection (meaning the connection increments the reference counter of `prepared_stmt`).

If `gda_stmt` changes or is destroyed, the the association will be lost and the connection will lose the reference it has on `prepared_stmt`.

`cnc` : | a GdaConnection object
`gda_stmt` : | a GdaStatement object
`prepared_stmt` : | a prepared statement object (as a GdaPStmt object, or more likely a descendant)

### gda_connection_del_prepared_statement ()

    void                gda_connection_del_prepared_statement
                                                            (GdaConnection *cnc,
                                                             GdaStatement *gda_stmt);

Removes any prepared statement associated to `gda_stmt` in `cnc`: this undoes what `gda_connection_add_prepared_statement()` does.

`cnc` : | a GdaConnection object
`gda_stmt` : | a GdaStatement object

### gda_connection_get_prepared_statement ()

    GdaPStmt *          gda_connection_get_prepared_statement
                                                            (GdaConnection *cnc,
                                                             GdaStatement *gda_stmt);

Retreives a pointer to an object representing a prepared statement for `gda_stmt` within `cnc`. The association must have been done using `gda_connection_add_prepared_statement()`.

`cnc` : | a GdaConnection object
`gda_stmt` : | a GdaStatement object
Returns : | the prepared statement, or `NULL` if no association exists

### gda_connection_internal_transaction_started ()

    void                gda_connection_internal_transaction_started
                                                            (GdaConnection *cnc,
                                                             const gchar *parent_trans,
                                                             const gchar *trans_name,
                                                             GdaTransactionIsolation isol_level);

Internal functions to be called by database providers when a transaction has been started to keep track of the transactional status of the connection.

Note: this function should not be called if `gda_connection_internal_statement_executed()` has already been called because a statement's execution was necessary to perform the action.

`cnc` : | a GdaConnection
`parent_trans` : | name of the parent transaction, or `NULL`
`trans_name` : | transaction's name, or `NULL`
`isol_level` : | isolation level.

### gda_connection_internal_transaction_rolledback ()

    void                gda_connection_internal_transaction_rolledback
                                                            (GdaConnection *cnc,
                                                             const gchar *trans_name);

Internal functions to be called by database providers when a transaction has been rolled back to keep track of the transactional status of the connection

Note: this function should not be called if `gda_connection_internal_statement_executed()` has already been called because a statement's execution was necessary to perform the action.

`cnc` : | a GdaConnection
`trans_name` : | transaction's name, or `NULL`

### gda_connection_internal_transaction_committed ()

    void                gda_connection_internal_transaction_committed
                                                            (GdaConnection *cnc,
                                                             const gchar *trans_name);

Internal functions to be called by database providers when a transaction has been committed to keep track of the transactional status of the connection

Note: this function should not be called if `gda_connection_internal_statement_executed()` has already been called because a statement's execution was necessary to perform the action.

`cnc` : | a GdaConnection
`trans_name` : | transaction's name, or `NULL`

### gda_connection_internal_statement_executed ()

    void                gda_connection_internal_statement_executed
                                                            (GdaConnection *cnc,
                                                             GdaStatement *stmt,
                                                             GdaSet *params,
                                                             GdaConnectionEvent *error);

Internal functions to be called by database providers when a statement has been executed to keep track of the transactional status of the connection

`cnc` : | a GdaConnection
`stmt` : | a GdaStatement which has been executed
`params` : | execution's parameters
`error` : | a GdaConnectionEvent if the execution failed, or `NULL`

### gda_connection_internal_savepoint_added ()

    void                gda_connection_internal_savepoint_added
                                                            (GdaConnection *cnc,
                                                             const gchar *parent_trans,
                                                             const gchar *svp_name);

Internal functions to be called by database providers when a savepoint has been added to keep track of the transactional status of the connection

Note: this function should not be called if `gda_connection_internal_statement_executed()` has already been called because a statement's execution was necessary to perform the action.

`cnc` : | a GdaConnection
`parent_trans` : | name of the parent transaction, or `NULL`
`svp_name` : | savepoint's name, or `NULL`

### gda_connection_internal_savepoint_rolledback ()

    void                gda_connection_internal_savepoint_rolledback
                                                            (GdaConnection *cnc,
                                                             const gchar *svp_name);

Internal functions to be called by database providers when a savepoint has been rolled back to keep track of the transactional status of the connection

Note: this function should not be called if `gda_connection_internal_statement_executed()` has already been called because a statement's execution was necessary to perform the action.

`cnc` : | a GdaConnection
`svp_name` : | savepoint's name, or `NULL`

### gda_connection_internal_savepoint_removed ()

    void                gda_connection_internal_savepoint_removed
                                                            (GdaConnection *cnc,
                                                             const gchar *svp_name);

Internal functions to be called by database providers when a savepoint has been removed to keep track of the transactional status of the connection

Note: this function should not be called if `gda_connection_internal_statement_executed()` has already been called because a statement's execution was necessary to perform the action.

`cnc` : | a GdaConnection
`svp_name` : | savepoint's name, or `NULL`

### gda_connection_internal_change_transaction_state ()

    void                gda_connection_internal_change_transaction_state
                                                            (GdaConnection *cnc,
                                                             GdaTransactionStatusState newstate);

Internal functions to be called by database providers to force a transaction status change.

`cnc` : | a GdaConnection
`newstate` : | the new state

### gda_meta_store_modify ()

    gboolean            gda_meta_store_modify               (GdaMetaStore *store,
                                                             const gchar *table_name,
                                                             GdaDataModel *new_data,
                                                             const gchar *condition,
                                                             GError **error,
                                                             ...);

Propagates an update to `store`, the update's contents is represented by `new_data`, this function is primarily reserved to database providers.

For example tell `store` to update its list of tables, `new_data` should contain the same columns as the "_tables" table of `store`, and contain one row per table in the store; there should not be any more argument after the `error` argument.

Now, to update only one table, the `new_data` data model should have one row for the table to update (or no row at all if the table does not exist anymore), and have values for the promary key of the "_tables" table of `store`, namely "table_catalog", "table_schema" and "table_name".

`store` : | a GdaMetaStore object
`table_name` : | the name of the table to modify within `store`
`new_data` : | a GdaDataModel containing the new data to set in `table_name`, or `NULL` (treated as a data model with no row at all)
`condition` : | SQL expression (which may contain variables) defining the rows which are being obsoleted by `new_data`, or `NULL`
`error` : | a place to store errors, or `NULL`
`...` : | a list of (variable name (gchar *), GValue *value) terminated with NULL, representing values for all the variables mentionned in `condition`.
Returns : | TRUE if no error occurred

### gda_meta_store_modify_with_context ()

    gboolean            gda_meta_store_modify_with_context  (GdaMetaStore *store,
                                                             GdaMetaContext *context,
                                                             GdaDataModel *new_data,
                                                             GError **error);

Propagates an update to `store`, the update's contents is represented by `new_data`, this function is primarily reserved to database providers.

`store` : | a GdaMetaStore object
`context` : | a GdaMetaContext context describing what to modify in `store`
`new_data` : | a GdaDataModel containing the new data to set in `table_name`, or `NULL` (treated as a data model with no row at all)
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred

### gda_compute_dml_statements ()

    gboolean            gda_compute_dml_statements          (GdaConnection *cnc,
                                                             GdaStatement *select_stmt,
                                                             gboolean require_pk,
                                                             GdaStatement **insert_stmt,
                                                             GdaStatement **update_stmt,
                                                             GdaStatement **delete_stmt,
                                                             GError **error);

Creates an INSERT, an UPDATE and a DELETE statement from a SELECT statement using the database metadata available in `cnc`'s meta store.

`cnc` : | a GdaConnection
`select_stmt` : | a SELECT GdaStatement (compound statements not handled)
`require_pk` : | TRUE if the created statement have to use a primary key
`insert_stmt` : | a place to store the created INSERT statement, or `NULL`
`update_stmt` : | a place to store the created UPDATE statement, or `NULL`
`delete_stmt` : | a place to store the created DELETE statement, or `NULL`
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred

### gda_compute_select_statement_from_update ()

    GdaSqlStatement *   gda_compute_select_statement_from_update
                                                            (GdaStatement *update_stmt,
                                                             GError **error);

Computes a SELECT statement which selects all the rows the `update_stmt` would update. Beware however that this GdaSqlStatement does not select anything (ie it would be rendered as "SELECT FROM ... WHERE ...") and before being useable, one needs to add some fields to actually select.

`update_stmt` : | an UPDATE statement
`error` : | a place to store errors, or `NULL`
Returns : | ; a new GdaStatement if no error occurred, or `NULL` otherwise

### gda_compute_unique_table_row_condition ()

    GdaSqlExpr *        gda_compute_unique_table_row_condition
                                                            (GdaSqlStatementSelect *stsel,
                                                             GdaMetaTable *mtable,
                                                             gboolean require_pk,
                                                             GError **error);

Computes a GdaSqlExpr expression which can be used in the WHERE clause of an UPDATE or DELETE statement when a row from the result of the `stsel` statement has to be modified.

`stsel` : | a GdaSqlSelectStatement
`mtable` : | a GdaMetaTable
`require_pk` : | set to TRUE if a primary key ir required
`error` : | a place to store errors, or `NULL`
Returns : | a new GdaSqlExpr, or `NULL` if an error occurred.

### gda_sql_any_part_check_structure ()

    gboolean            gda_sql_any_part_check_structure    (GdaSqlAnyPart *node,
                                                             GError **error);

Checks for any error in `node`'s structure to make sure it is valid. This is the same as `gda_sql_statement_check_structure()` but for individual GdaSqlAnyPart parts. This function is mainly for database provider's implementations

`node` : | a GdaSqlAnyPart pointer
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred