GdaServerProvider

GdaServerProvider — Base class for all the DBMS providers

Functions

const gchar * gda_server_provider_get_version ()
GdaServerProviderInfo * gda_server_provider_get_info ()
gboolean gda_server_provider_open_connection ()
gboolean gda_server_provider_close_connection ()
const gchar * gda_server_provider_get_server_version ()
const gchar * gda_server_provider_get_database ()
gboolean gda_server_provider_change_database ()
gboolean gda_server_provider_supports_operation ()
GdaServerOperation * gda_server_provider_create_operation ()
gchar * gda_server_provider_render_operation ()
gboolean gda_server_provider_perform_operation ()
GList * gda_server_provider_execute_command ()
GdaObject * gda_server_provider_execute_query ()
gchar * gda_server_provider_get_last_insert_id ()
gboolean gda_server_provider_begin_transaction ()
gboolean gda_server_provider_commit_transaction ()
gboolean gda_server_provider_rollback_transaction ()
gboolean gda_server_provider_add_savepoint ()
gboolean gda_server_provider_rollback_savepoint ()
gboolean gda_server_provider_delete_savepoint ()
gboolean gda_server_provider_supports_feature ()
GdaDataModel * gda_server_provider_get_schema ()
GdaDataHandler * gda_server_provider_get_data_handler_gtype ()
GdaDataHandler * gda_server_provider_get_data_handler_dbms ()
GValue * gda_server_provider_string_to_value ()
gchar * gda_server_provider_value_to_sql_string ()
const gchar * gda_server_provider_get_default_dbms_type ()
gchar * gda_server_provider_escape_string ()
gchar * gda_server_provider_unescape_string ()

Types and Values

Object Hierarchy

    GObject
    ╰── GdaServerProvider
        ╰── GdaSqliteProvider

Description

The GdaServerProvider class is a virtual class which all the DBMS providers must inherit, and implement its virtual mathods.

Functions

gda_server_provider_get_version ()

const gchar *
gda_server_provider_get_version (GdaServerProvider *provider);

Get the version of the given provider.

Parameters

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

Parameters

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.

Parameters

provider

a GdaServerProvider object.

 

cnc

a GdaConnection object.

 

username

user name for logging in.

 

password

password for authentication.

 

Returns

TRUE if no error occurred


gda_server_provider_close_connection ()

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

gda_server_provider_get_server_version ()

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

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.

Parameters

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.

Parameters

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.

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

Parameters

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.

Parameters

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 .

Parameters

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

See the documentation of the gda_connection_execute_command() for information about the params list of parameters.

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

Parameters

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)

Parameters

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.

Parameters

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

Parameters

name

the name of the transation to start

 

error

a place to store errors, or NULL

 

gda_server_provider_commit_transaction ()

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

Parameters

name

the name of the transation to commit

 

error

a place to store errors, or NULL

 

gda_server_provider_rollback_transaction ()

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

Parameters

name

the name of the transation to commit

 

error

a place to store errors, or NULL

 

gda_server_provider_add_savepoint ()

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

Parameters

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

Parameters

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

Parameters

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

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.

Parameters

provider

a GdaServerProvider object

 

cnc

a GdaConnection object, or NULL

 

schema

the requested kind of information

 

params

optional parameters

 

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 .

Parameters

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 .

Parameters

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

Parameters

provider

a server provider.

 

cnc

a GdaConnection object.

 

string

the SQL string to convert to a value

 

prefered_type

a GType

 

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

Parameters

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

Parameters

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.

Parameters

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

Parameters

provider

a server provider.

 

cnc

a GdaConnection object, or NULL

 

str

a string to escape

 

Returns

a new string

Types and Values

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;