## GdaServerProvider

GdaServerProvider

## Synopsis

                        GdaServerProvider;
                        GdaServerProviderInfo;
    const gchar*        gda_server_provider_get_version     (GdaServerProvider *provider);
    GdaServerProviderInfo* gda_server_provider_get_info     (GdaServerProvider *provider,
                                                             GdaConnection *cnc);
    gboolean            gda_server_provider_open_connection (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaQuarkList *params,
                                                             const gchar *username,
                                                             const gchar *password);
    gboolean            gda_server_provider_close_connection
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc);
    const gchar*        gda_server_provider_get_server_version
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc);
    const gchar*        gda_server_provider_get_database    (GdaServerProvider *provider,
                                                             GdaConnection *cnc);
    gboolean            gda_server_provider_change_database (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *name);
    gboolean            gda_server_provider_supports_operation
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaServerOperationType type,
                                                             GdaParameterList *options);
    GdaServerOperation* gda_server_provider_create_operation
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaServerOperationType type,
                                                             GdaParameterList *options,
                                                             GError **error);
    gchar*              gda_server_provider_render_operation
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaServerOperation *op,
                                                             GError **error);
    gboolean            gda_server_provider_perform_operation
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaServerOperation *op,
                                                             GError **error);
    GList*              gda_server_provider_execute_command (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaCommand *cmd,
                                                             GdaParameterList *params);
    GdaObject*          gda_server_provider_execute_query   (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaQuery *query,
                                                             GdaParameterList *params);
    gchar*              gda_server_provider_get_last_insert_id
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaDataModel *recset);
    gboolean            gda_server_provider_begin_transaction
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *name,
                                                             GdaTransactionIsolation level,
                                                             GError **error);
    gboolean            gda_server_provider_commit_transaction
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *name,
                                                             GError **error);
    gboolean            gda_server_provider_rollback_transaction
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *name,
                                                             GError **error);
    gboolean            gda_server_provider_add_savepoint   (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *name,
                                                             GError **error);
    gboolean            gda_server_provider_rollback_savepoint
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *name,
                                                             GError **error);
    gboolean            gda_server_provider_delete_savepoint
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *name,
                                                             GError **error);
    gboolean            gda_server_provider_supports_feature
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaConnectionFeature feature);
    GdaDataModel*       gda_server_provider_get_schema      (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaConnectionSchema schema,
                                                             GdaParameterList *params,
                                                             GError **error);
    GdaDataHandler*     gda_server_provider_get_data_handler_gtype
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GType for_type);
    GdaDataHandler*     gda_server_provider_get_data_handler_dbms
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *for_type);
    GValue*             gda_server_provider_string_to_value (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *string,
                                                             GType prefered_type,
                                                             gchar **dbms_type);
    gchar*              gda_server_provider_value_to_sql_string
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GValue *from);
    const gchar*        gda_server_provider_get_default_dbms_type
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GType type);
    gchar*              gda_server_provider_escape_string   (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *str);
    gchar*              gda_server_provider_unescape_string (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *str);

## Object Hierarchy

      GObject
       +----GdaServerProvider

## Description

## Details

### GdaServerProvider

    typedef struct _GdaServerProvider GdaServerProvider;

### GdaServerProviderInfo

    typedef struct {
            gchar         *provider_name; /* equal to the return of gda_connection_get_provider() */

            /*
             * TRUE if all comparisons of names can be done on the lower case versions of the objects names
             */
            gboolean       is_case_insensitive;

            /*
             * TRUE to suppose that there are implicit casts available for data types which have
             * the same gda type
             */
            gboolean       implicit_data_types_casts;

            /*
             * TRUE if writing "... FROM mytable AS alias..." is ok, and FALSE if we need to write this as
             * "... FROM mytable alias..."
             */
            gboolean       alias_needs_as_keyword;

    	/* TRUE is tables can be aliased in SELECT queries*/
    	gboolean       supports_alias;

    	/* TRUE if it is possible to write "SELECT table.field ..." or if it is only possible
    	 * to write "SELECT field..."
    	 */
    	gboolean       supports_prefixed_fields;

    	/* TRUE if non lower case identifiers must be surrounded by double quotes to distinguish them
    	 * with their lower case equivalent, that is TRUE if by default the non lower case identifiers
    	 * are converted into lower case.
    	 */
    	gboolean       quote_non_lc_identifiers;

    	/* reserved for extensions */
    	gboolean       reserved[20];
    } GdaServerProviderInfo;

### gda_server_provider_get_version ()

    const gchar*        gda_server_provider_get_version     (GdaServerProvider *provider);

Get the version of the given provider.

`provider` : | a GdaServerProvider object.
Returns : | a string containing the version identification.

### gda_server_provider_get_info ()

    GdaServerProviderInfo* gda_server_provider_get_info     (GdaServerProvider *provider,
                                                             GdaConnection *cnc);

Retreive some information specific to the provider. The returned GdaServerProviderInfo structure must not be modified

`provider` : | a GdaServerProvider object.
`cnc` : | a GdaConnection, or `NULL`
Returns : | a GdaServerProviderInfo pointer or `NULL` if an error occurred

### gda_server_provider_open_connection ()

    gboolean            gda_server_provider_open_connection (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaQuarkList *params,
                                                             const gchar *username,
                                                             const gchar *password);

Tries to open a new connection on the given GdaServerProvider object.

`provider` : | a GdaServerProvider object.
`cnc` : | a GdaConnection object.
`params` : |
`username` : | user name for logging in.
`password` : | password for authentication.
Returns : | a newly-allocated GdaServerConnection object, or NULL if it fails.

### gda_server_provider_close_connection ()

    gboolean            gda_server_provider_close_connection
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc);

`provider` : |
`cnc` : |
Returns : |

### gda_server_provider_get_server_version ()

    const gchar*        gda_server_provider_get_server_version
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc);

`provider` : |
`cnc` : |
Returns : |

### gda_server_provider_get_database ()

    const gchar*        gda_server_provider_get_database    (GdaServerProvider *provider,
                                                             GdaConnection *cnc);

Proxy the call to the get_database method on the GdaServerProvider class to the corresponding provider.

`provider` : | a GdaServerProvider object.
`cnc` : | a GdaConnection object.
Returns : | the name of the current database.

### gda_server_provider_change_database ()

    gboolean            gda_server_provider_change_database (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *name);

Proxy the call to the change_database method on the " GdaServerProvider class to the corresponding provider.

`provider` : | a GdaServerProvider object.
`cnc` : | a GdaConnection object.
`name` : | database name.
Returns : | `TRUE` if successful, `FALSE` otherwise.

### gda_server_provider_supports_operation ()

    gboolean            gda_server_provider_supports_operation
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaServerOperationType type,
                                                             GdaParameterList *options);

Tells if `provider` supports the `type` of operation on the `cnc` connection, using the (optional) `options` parameters.

`provider` : | a GdaServerProvider object
`cnc` : | a GdaConnection object which would be used to perform an action
`type` : | the type of operation requested
`options` : | a list of named parameters, or `NULL`
Returns : | TRUE if the operation is supported

### gda_server_provider_create_operation ()

    GdaServerOperation* gda_server_provider_create_operation
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaServerOperationType type,
                                                             GdaParameterList *options,
                                                             GError **error);

Creates a new GdaServerOperation object which can be modified in order to perform the `type` type of action. The `options` can contain:

- parameters which ID is a path in the resulting GdaServerOperation object, to initialize some value
- parameters which may change the contents of the GdaServerOperation, see this section for more information

`provider` : | a GdaServerProvider object
`cnc` : | a GdaConnection object which will be used to perform an action
`type` : | the type of operation requested
`options` : | an optional list of parameters
`error` : | a place to store an error, or `NULL`
Returns : | a new GdaServerOperation object, or `NULL` in the provider does not support the `type` type of operation or if an error occurred

### gda_server_provider_render_operation ()

    gchar*              gda_server_provider_render_operation
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaServerOperation *op,
                                                             GError **error);

Creates an SQL statement (possibly using some specific extensions of the DBMS) corresponding to the `op` operation.

`provider` : | a GdaServerProvider object
`cnc` : | a GdaConnection object which will be used to perform an action
`op` : | a GdaServerOperation object
`error` : | a place to store an error, or `NULL`
Returns : | a new string, or `NULL` if an error occurred or operation cannot be rendered as SQL.

### gda_server_provider_perform_operation ()

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

Performs the operation described by `op`.

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

### gda_server_provider_execute_command ()

    GList*              gda_server_provider_execute_command (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaCommand *cmd,
                                                             GdaParameterList *params);

Executes one or more SQL statements stored in `command`, and returns a list of GdaDataModel and/or GdaParameterList (or `NULL`) objects for each SQL statement in `command` following the rule (the number and order of items contained in the returned list is the same as the number and order of SQL queries in `command` if there is no error, otherwise it depends on the execution options in `params`):

- A GdaDataModel is in the list if the statement was a SELECT statement and the statement was successufully executed

- A GdaParameterList is in the list if the statement was not a SELECT statement and the statement was successufully executed. In this case (if the provider supports it), then the GdaParameterList may contain:

  - a (gint) GdaParameter named "IMPACTED_ROWS"

  - a (GObject) GdaParameter named "EVENT" which contains a GdaConnectionEvent

- `NULL` is in the list if the correcponding statement could not be executed

For every executed statement, a GdaDataModel, a GdaParameterList or `NULL` will be appended to the returned list. The returned list may contain fewer items than the `cmd` command contained statements depending on the options of `command` (see `gda_command_set_options()`).

`provider` : | a GdaServerProvider object
`cnc` : | a GdaConnection object using
`cmd` : | a GdaCommand
`params` : | a GdaParameterList containing a list of optional parameters
Returns : | a new list, or `NULL`

### gda_server_provider_execute_query ()

    GdaObject*          gda_server_provider_execute_query   (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaQuery *query,
                                                             GdaParameterList *params);

Executes the `query` query, and returns:

- A GdaDataModel if the query was a SELECT statement and the statement was successufully executed

- A GdaParameterList if the query was not a SELECT query and the query was successufully executed. In this case (if the provider supports it), then the GdaParameterList may contain:

  - a (gint) GdaParameter named "IMPACTED_ROWS"

  - a (GObject) GdaParameter named "EVENT" which contains a GdaConnectionEvent

- `NULL` is in the list if the query could not be executed

The differences between this function and `gda_server_provider_execute_command()` are:

- Only one query can be executed at a time

- If the database provider supports it, prepared statements can be used

- Blobs are handled correctly (because blobs are usually not handled using SQL)

`provider` : | a GdaServerProvider object
`cnc` : | a GdaConnection object using
`query` : | a GdaQuery
`params` : | a GdaParameterList object obtained using gda_query_get_parameter_list(`query`)
Returns : | a new (GdaDataModel or GdaParameterList) object, or `NULL`

### gda_server_provider_get_last_insert_id ()

    gchar*              gda_server_provider_get_last_insert_id
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaDataModel *recset);

Retrieve from the given GdaServerProvider the ID of the last inserted row. A connection must be specified, and, optionally, a result set. If not NULL, the provider should try to get the last insert ID for the given result set.

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

`provider` : | a GdaServerProvider object.
`cnc` : | connection to act upon.
`recset` : | resultset to get the last insert ID from.
Returns : | a string representing the ID of the last inserted row, or NULL if an error occurred or no row has been inserted. It is the caller's reponsibility to free the returned string.

### gda_server_provider_begin_transaction ()

    gboolean            gda_server_provider_begin_transaction
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *name,
                                                             GdaTransactionIsolation level,
                                                             GError **error);

`provider` : |
`cnc` : |
`name` : | the name of the transation to start
`level` : |
`error` : | a place to store errors, or `NULL`
Returns : |

### gda_server_provider_commit_transaction ()

    gboolean            gda_server_provider_commit_transaction
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *name,
                                                             GError **error);

`provider` : |
`cnc` : |
`name` : | the name of the transation to commit
`error` : | a place to store errors, or `NULL`
Returns : |

### gda_server_provider_rollback_transaction ()

    gboolean            gda_server_provider_rollback_transaction
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *name,
                                                             GError **error);

`provider` : |
`cnc` : |
`name` : | the name of the transation to commit
`error` : | a place to store errors, or `NULL`
Returns : |

### gda_server_provider_add_savepoint ()

    gboolean            gda_server_provider_add_savepoint   (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *name,
                                                             GError **error);

`provider` : | a GdaServerProvider object
`cnc` : | a GdaConnection object
`name` : | name of the savepoint to add
`error` : | a place to store errors or `NULL`
Returns : | TRUE if no error occurred

### gda_server_provider_rollback_savepoint ()

    gboolean            gda_server_provider_rollback_savepoint
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *name,
                                                             GError **error);

`provider` : | a GdaServerProvider object
`cnc` : | a GdaConnection object
`name` : | name of the savepoint to rollback to
`error` : | a place to store errors or `NULL`
Returns : | TRUE if no error occurred

### gda_server_provider_delete_savepoint ()

    gboolean            gda_server_provider_delete_savepoint
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *name,
                                                             GError **error);

`provider` : | a GdaServerProvider object
`cnc` : | a GdaConnection object
`name` : | name of the savepoint to delete
`error` : | a place to store errors or `NULL`
Returns : | TRUE if no error occurred

### gda_server_provider_supports_feature ()

    gboolean            gda_server_provider_supports_feature
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaConnectionFeature feature);

`provider` : |
`cnc` : |
`feature` : |
Returns : |

### gda_server_provider_get_schema ()

    GdaDataModel*       gda_server_provider_get_schema      (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GdaConnectionSchema schema,
                                                             GdaParameterList *params,
                                                             GError **error);

Get a GdaDataModel containing the requested information. See this section for more information on the columns of the returned GdaDataModel depending on requested `schema`, and for the possible parameters of `params`, see the `get_schema()` virtual method for providers for more details.

`provider` : | a GdaServerProvider object
`cnc` : | a GdaConnection object, or `NULL`
`schema` : | the requested kind of information
`params` : | optional parameters
`error` : |
Returns : | a new GdaDataModel, or `NULL` if an error occurred.

### gda_server_provider_get_data_handler_gtype ()

    GdaDataHandler*     gda_server_provider_get_data_handler_gtype
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GType for_type);

Find a GdaDataHandler object to manipulate data of type `for_type`.

`provider` : | a server provider.
`cnc` : | a GdaConnection object, or `NULL`
`for_type` : | a GType
Returns : | a GdaDataHandler, or `NULL` if the provider does not support the requested `for_type` data type

### gda_server_provider_get_data_handler_dbms ()

    GdaDataHandler*     gda_server_provider_get_data_handler_dbms
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *for_type);

Find a GdaDataHandler object to manipulate data of type `for_type`.

`provider` : | a server provider.
`cnc` : | a GdaConnection object, or `NULL`
`for_type` : | a DBMS type definition
Returns : | a GdaDataHandler, or `NULL` if the provider does not know about the `for_type` type

### gda_server_provider_string_to_value ()

    GValue*             gda_server_provider_string_to_value (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *string,
                                                             GType prefered_type,
                                                             gchar **dbms_type);

Use `provider` to create a new GValue from a single string representation.

The `prefered_type` can optionnaly ask `provider` to return a GValue of the requested type (but if such a value can't be created from `string`, then `NULL` is returned); pass G_TYPE_INVALID if any returned type is acceptable.

The returned value is either a new GValue or `NULL` in the following cases: - `string` cannot be converted to `prefered_type` type - the provider does not handle `prefered_type` - the provider could not make a GValue from `string`

`provider` : | a server provider.
`cnc` : | a GdaConnection object.
`string` : | the SQL string to convert to a value
`prefered_type` : | a GType
`dbms_type` : |
Returns : | a new GValue, or `NULL`

### gda_server_provider_value_to_sql_string ()

    gchar*              gda_server_provider_value_to_sql_string
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GValue *from);

Produces a fully quoted and escaped string from a GValue

`provider` : | a server provider.
`cnc` : | a GdaConnection object, or `NULL`
`from` : | GValue to convert from
Returns : | escaped and quoted value or NULL if not supported.

### gda_server_provider_get_default_dbms_type ()

    const gchar*        gda_server_provider_get_default_dbms_type
                                                            (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             GType type);

Get the name of the most common data type which has `type` type.

The returned value may be `NULL` either if the provider does not implement that method, or if there is no DBMS data type which could contain data of the `g_type` type (for example `NULL` may be returned if a DBMS has integers only up to 4 bytes and a G_TYPE_INT64 is requested).

`provider` : | a server provider.
`cnc` : | a GdaConnection object or `NULL`
`type` : | a GType value type
Returns : | the name of the DBMS type, or `NULL`

### gda_server_provider_escape_string ()

    gchar*              gda_server_provider_escape_string   (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *str);

Escapes `str` for use within an SQL command (to avoid SQL injection attacks). Note that the returned value still needs to be enclosed in single quotes before being used in an SQL statement.

`provider` : | a server provider.
`cnc` : | a GdaConnection object, or `NULL`
`str` : | a string to escape
Returns : | a new string suitable to use in SQL statements

### gda_server_provider_unescape_string ()

    gchar*              gda_server_provider_unescape_string (GdaServerProvider *provider,
                                                             GdaConnection *cnc,
                                                             const gchar *str);

Unescapes `str` for use within an SQL command. This is the exact opposite of `gda_server_provider_escape_string()`.

`provider` : | a server provider.
`cnc` : | a GdaConnection object, or `NULL`
`str` : | a string to escape
Returns : | a new string