![]() |
![]() |
![]() |
GNOME Data Access 4 manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
GdaServerProvider; GdaServerProviderClass; enum GdaServerProviderError; #define GDA_SERVER_PROVIDER_ERROR GdaServerProviderMeta; void (*GdaServerProviderAsyncCallback) (GdaServerProvider *provider, GdaConnection *cnc, guint task_id, gboolean result_status, const GError *error, gpointer data); void (*GdaServerProviderExecCallback) (GdaServerProvider *provider, GdaConnection *cnc, guint task_id, GObject *result_obj, const GError *error, gpointer data); const gchar * gda_server_provider_get_name (GdaServerProvider *provider); const gchar * gda_server_provider_get_version (GdaServerProvider *provider); const gchar * gda_server_provider_get_server_version (GdaServerProvider *provider, GdaConnection *cnc); gboolean gda_server_provider_supports_operation (GdaServerProvider *provider, GdaConnection *cnc, GdaServerOperationType type, GdaSet *options); GdaServerOperation * gda_server_provider_create_operation (GdaServerProvider *provider, GdaConnection *cnc, GdaServerOperationType type, GdaSet *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); GdaSqlParser * gda_server_provider_create_parser (GdaServerProvider *provider, GdaConnection *cnc); gboolean gda_server_provider_supports_feature (GdaServerProvider *provider, GdaConnection *cnc, GdaConnectionFeature feature); GdaDataHandler * gda_server_provider_get_data_handler_g_type (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 preferred_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);
The GdaServerProvider class is a virtual class which all the DBMS providers must inherit, and implement its virtual methods.
See the Virtual methods for providers section for more information about how to implement the virtual methods.
typedef struct { GObjectClass parent_class; /* provider information */ GThread * limiting_thread; /* if not NULL, then using the provider will be limited to this thread */ const gchar *(* get_name) (GdaServerProvider *provider); const gchar *(* get_version) (GdaServerProvider *provider); const gchar *(* get_server_version) (GdaServerProvider *provider, GdaConnection *cnc); gboolean (* supports_feature) (GdaServerProvider *provider, GdaConnection *cnc, GdaConnectionFeature feature); /* types and values manipulation */ GdaDataHandler *(* get_data_handler) (GdaServerProvider *provider, GdaConnection *cnc, GType g_type, const gchar *dbms_type); const gchar *(*get_def_dbms_type) (GdaServerProvider *provider, GdaConnection *cnc, GType g_type); gchar *(*escape_string) (GdaServerProvider *provider, GdaConnection *cnc, const gchar *str); gchar *(*unescape_string) (GdaServerProvider *provider, GdaConnection *cnc, const gchar *str); /* connections management */ gboolean (* open_connection) (GdaServerProvider *provider, GdaConnection *cnc, GdaQuarkList *params, GdaQuarkList *auth, guint *task_id, GdaServerProviderAsyncCallback async_cb, gpointer cb_data); gboolean (* close_connection) (GdaServerProvider *provider, GdaConnection *cnc); const gchar *(* get_database) (GdaServerProvider *provider, GdaConnection *cnc); /* operations */ gboolean (* supports_operation) (GdaServerProvider *provider, GdaConnection *cnc, GdaServerOperationType type, GdaSet *options); GdaServerOperation *(* create_operation) (GdaServerProvider *provider, GdaConnection *cnc, GdaServerOperationType type, GdaSet *options, GError **error); gchar *(* render_operation) (GdaServerProvider *provider, GdaConnection *cnc, GdaServerOperation *op, GError **error); gboolean (* perform_operation) (GdaServerProvider *provider, GdaConnection *cnc, GdaServerOperation *op, guint *task_id, GdaServerProviderAsyncCallback async_cb, gpointer cb_data, GError **error); /* transactions */ gboolean (* begin_transaction) (GdaServerProvider *provider, GdaConnection *cnc, const gchar *name, GdaTransactionIsolation level, GError **error); gboolean (* commit_transaction) (GdaServerProvider *provider, GdaConnection *cnc, const gchar *name, GError **error); gboolean (* rollback_transaction) (GdaServerProvider *provider, GdaConnection *cnc, const gchar *name, GError **error); gboolean (* add_savepoint) (GdaServerProvider *provider, GdaConnection *cnc, const gchar *name, GError **error); gboolean (* rollback_savepoint) (GdaServerProvider *provider, GdaConnection *cnc, const gchar *name, GError **error); gboolean (* delete_savepoint) (GdaServerProvider *provider, GdaConnection *cnc, const gchar *name, GError **error); /* GdaStatement */ GdaSqlParser *(* create_parser) (GdaServerProvider *provider, GdaConnection *cnc); gchar *(* statement_to_sql) (GdaServerProvider *provider, GdaConnection *cnc, GdaStatement *stmt, GdaSet *params, GdaStatementSqlFlag flags, GSList **params_used, GError **error); gboolean (* statement_prepare) (GdaServerProvider *provider, GdaConnection *cnc, GdaStatement *stmt, GError **error); GObject *(* statement_execute) (GdaServerProvider *provider, GdaConnection *cnc, GdaStatement *stmt, GdaSet *params, GdaStatementModelUsage model_usage, GType *col_types, GdaSet **last_inserted_row, guint *task_id, GdaServerProviderExecCallback exec_cb, gpointer cb_data, GError **error); /* Misc */ gboolean (* is_busy) (GdaServerProvider *provider, GdaConnection *cnc, GError **error); gboolean (* cancel) (GdaServerProvider *provider, GdaConnection *cnc, guint task_id, GError **error); GdaConnection *(* create_connection) (GdaServerProvider *provider); /* meta data reporting */ GdaServerProviderMeta meta_funcs; /* distributed transaction */ GdaServerProviderXa *xa_funcs; /* it is a pointer! => set to %NULL if unsupported by provider */ /* SQL identifiers quoting */ gchar *(* identifier_quote) (GdaServerProvider *provider, GdaConnection *cnc, const gchar *id, gboolean for_meta_store, gboolean force_quotes); /* Async. handling@ */ gboolean (*handle_async) (GdaServerProvider *provider, GdaConnection *cnc, GError **error); /* Padding for future expansion */ void (*_gda_reserved3) (void); void (*_gda_reserved4) (void); void (*_gda_reserved5) (void); void (*_gda_reserved6) (void); } GdaServerProviderClass;
typedef enum { GDA_SERVER_PROVIDER_METHOD_NON_IMPLEMENTED_ERROR, GDA_SERVER_PROVIDER_PREPARE_STMT_ERROR, GDA_SERVER_PROVIDER_EMPTY_STMT_ERROR, GDA_SERVER_PROVIDER_MISSING_PARAM_ERROR, GDA_SERVER_PROVIDER_STATEMENT_EXEC_ERROR, GDA_SERVER_PROVIDER_OPERATION_ERROR, GDA_SERVER_PROVIDER_INTERNAL_ERROR, GDA_SERVER_PROVIDER_BUSY_ERROR, GDA_SERVER_PROVIDER_NON_SUPPORTED_ERROR, GDA_SERVER_PROVIDER_SERVER_VERSION_ERROR, GDA_SERVER_PROVIDER_DATA_ERROR } GdaServerProviderError;
typedef struct { /* _information_schema_catalog_name */ gboolean (*_info) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); /* _builtin_data_types */ gboolean (*_btypes) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); /* _udt */ gboolean (*_udt) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*udt) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *udt_catalog, const GValue *udt_schema); /* _udt_columns */ gboolean (*_udt_cols) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*udt_cols) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *udt_catalog, const GValue *udt_schema, const GValue *udt_name); /* _enums */ gboolean (*_enums) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*enums) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *udt_catalog, const GValue *udt_schema, const GValue *udt_name); /* _domains */ gboolean (*_domains) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*domains) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *domain_catalog, const GValue *domain_schema); /* _domain_constraints */ gboolean (*_constraints_dom) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*constraints_dom) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *domain_catalog, const GValue *domain_schema, const GValue *domain_name); /* _element_types */ gboolean (*_el_types) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*el_types) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *specific_name); /* _collations */ gboolean (*_collations) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*collations) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *collation_catalog, const GValue *collation_schema, const GValue *collation_name_n); /* _character_sets */ gboolean (*_character_sets) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*character_sets) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *chset_catalog, const GValue *chset_schema, const GValue *chset_name_n); /* _schemata */ gboolean (*_schemata) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*schemata) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *catalog_name, const GValue *schema_name_n); /* _tables or _views */ gboolean (*_tables_views) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*tables_views) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *table_catalog, const GValue *table_schema, const GValue *table_name_n); /* _columns */ gboolean (*_columns) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*columns) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *table_catalog, const GValue *table_schema, const GValue *table_name); /* _view_column_usage */ gboolean (*_view_cols) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*view_cols) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *view_catalog, const GValue *view_schema, const GValue *view_name); /* _table_constraints */ gboolean (*_constraints_tab) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*constraints_tab) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *table_catalog, const GValue *table_schema, const GValue *table_name, const GValue *constraint_name_n); /* _referential_constraints */ gboolean (*_constraints_ref) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*constraints_ref) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *table_catalog, const GValue *table_schema, const GValue *table_name, const GValue *constraint_name); /* _key_column_usage */ gboolean (*_key_columns) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*key_columns) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *table_catalog, const GValue *table_schema, const GValue *table_name, const GValue *constraint_name); /* _check_column_usage */ gboolean (*_check_columns) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*check_columns) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *table_catalog, const GValue *table_schema, const GValue *table_name, const GValue *constraint_name); /* _triggers */ gboolean (*_triggers) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*triggers) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *table_catalog, const GValue *table_schema, const GValue *table_name); /* _routines */ gboolean (*_routines) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*routines) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *routine_catalog, const GValue *routine_schema, const GValue *routine_name_n); /* _routine_columns */ gboolean (*_routine_col) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*routine_col) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *rout_catalog, const GValue *rout_schema, const GValue *rout_name); /* _parameters */ gboolean (*_routine_par) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*routine_par) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *rout_catalog, const GValue *rout_schema, const GValue *rout_name); /* _table_indexes */ gboolean (*_indexes_tab) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*indexes_tab) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *table_catalog, const GValue *table_schema, const GValue *table_name, const GValue *index_name_n); /* _index_column_usage */ gboolean (*_index_cols) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **); gboolean (*index_cols) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **, const GValue *table_catalog, const GValue *table_schema, const GValue *table_name, const GValue *index_name); /* Padding for future expansion */ void (*_gda_reserved5) (void); void (*_gda_reserved6) (void); void (*_gda_reserved7) (void); void (*_gda_reserved8) (void); void (*_gda_reserved9) (void); void (*_gda_reserved10) (void); void (*_gda_reserved11) (void); void (*_gda_reserved12) (void); void (*_gda_reserved13) (void); void (*_gda_reserved14) (void); void (*_gda_reserved15) (void); void (*_gda_reserved16) (void); } GdaServerProviderMeta;
These methods must be implemented by providers to update a connection's associated metadata (in a GdaMetaStore object), see the Virtual methods for providers/Methods - metadata for more information.
void (*GdaServerProviderAsyncCallback) (GdaServerProvider *provider, GdaConnection *cnc, guint task_id, gboolean result_status, const GError *error, gpointer data);
Function to be called by Libgda when the associated asynchronous method invoked finishes.
|
|
|
|
|
|
|
|
|
|
|
void (*GdaServerProviderExecCallback) (GdaServerProvider *provider, GdaConnection *cnc, guint task_id, GObject *result_obj, const GError *error, gpointer data);
Function to be called by Libgda when the associated asynchronous method invoked finishes.
|
|
|
|
|
|
|
|
|
|
|
const gchar * gda_server_provider_get_name (GdaServerProvider *provider);
Get the name (identifier) of the provider
|
a GdaServerProvider object. |
Returns : |
a string containing the provider's name |
const gchar * gda_server_provider_get_version (GdaServerProvider *provider);
Get the version of the provider.
|
a GdaServerProvider object. |
Returns : |
a string containing the version identification. |
const gchar * gda_server_provider_get_server_version (GdaServerProvider *provider, GdaConnection *cnc);
Get the version of the database to which the connection is opened.
|
a GdaServerProvider object. |
|
a GdaConnection object |
Returns : |
a (read only) string, or NULL if an error occurred
|
gboolean gda_server_provider_supports_operation (GdaServerProvider *provider, GdaConnection *cnc, GdaServerOperationType type, GdaSet *options);
Tells if provider
supports the type
of operation on the cnc
connection, using the
(optional) options
parameters.
|
a GdaServerProvider object |
|
a GdaConnection object which would be used to perform an action, or NULL
|
|
the type of operation requested |
|
a list of named parameters, or NULL
|
Returns : |
TRUE if the operation is supported |
GdaServerOperation * gda_server_provider_create_operation (GdaServerProvider *provider, GdaConnection *cnc, GdaServerOperationType type, GdaSet *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:
|
a GdaServerProvider object |
|
a GdaConnection object which will be used to perform an action, or NULL
|
|
the type of operation requested |
|
an optional list of parameters |
|
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
|
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. Note that the returned string may actually contain more than one SQL statement.
This function's purpose is mainly informative to get the actual SQL code which would be executed to perform
the operation; to actually perform the operation, use gda_server_provider_perform_operation()
.
|
a GdaServerProvider object |
|
a GdaConnection object which will be used to render the action, or NULL
|
|
a GdaServerOperation object |
|
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.
|
gboolean gda_server_provider_perform_operation (GdaServerProvider *provider, GdaConnection *cnc, GdaServerOperation *op, GError **error);
Performs the operation described by op
. Note that op
is not destroyed by this method
and can be reused.
|
a GdaServerProvider object |
|
a GdaConnection object which will be used to perform the action, or NULL
|
|
a GdaServerOperation object |
|
a place to store an error, or NULL
|
Returns : |
TRUE if no error occurred |
GdaSqlParser * gda_server_provider_create_parser (GdaServerProvider *provider, GdaConnection *cnc);
Creates a new GdaSqlParser object which is adapted to provider
(and possibly depending on
cnc
for the actual database version).
If prov
does not have its own parser, then NULL
is returned, and a general SQL parser can be obtained
using gda_sql_parser_new()
.
|
a GdaServerProvider provider object |
|
a GdaConnection, or NULL
|
Returns : |
a new GdaSqlParser object, or NULL .
|
gboolean gda_server_provider_supports_feature (GdaServerProvider *provider, GdaConnection *cnc, GdaConnectionFeature feature);
Tests if a feature is supported
|
a GdaServerProvider object |
|
a GdaConnection object, or NULL
|
|
GdaConnectionFeature feature to test |
Returns : |
TRUE if feature is supported
|
GdaDataHandler * gda_server_provider_get_data_handler_g_type (GdaServerProvider *provider, GdaConnection *cnc, GType for_type);
Find a GdaDataHandler object to manipulate data of type for_type
. The returned object must not be modified.
|
a server provider. |
|
a GdaConnection object, or NULL
|
|
a GType |
Returns : |
a GdaDataHandler, or NULL if the provider does not support the requested for_type data type
|
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
.
|
a server provider. |
|
a GdaConnection object, or NULL
|
|
a DBMS type definition |
Returns : |
a GdaDataHandler, or NULL if the provider does not know about the for_type type
|
GValue * gda_server_provider_string_to_value (GdaServerProvider *provider, GdaConnection *cnc, const gchar *string, GType preferred_type, gchar **dbms_type);
Use provider
to create a new GValue from a single string representation.
The preferred_type
can optionally 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 preferred_type
type
- the provider does not handle preferred_type
- the provider could not make a GValue from string
If dbms_type
is not NULL
, then if will contain a constant string representing
the database type used for the conversion if the conversion was successfull, or NULL
otherwise.
|
a server provider. |
|
a GdaConnection object, or NULL
|
|
the SQL string to convert to a value |
|
a GType, or G_TYPE_INVALID |
|
place to get the actual database type used if the conversion succeeded, or NULL
|
Returns : |
a new GValue, or NULL
|
gchar * gda_server_provider_value_to_sql_string (GdaServerProvider *provider, GdaConnection *cnc, GValue *from);
Produces a fully quoted and escaped string from a GValue
|
a server provider. |
|
a GdaConnection object, or NULL
|
|
GValue to convert from |
Returns : |
escaped and quoted value or NULL if not supported. |
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).
|
a server provider. |
|
a GdaConnection object or NULL
|
|
a GType value type |
Returns : |
the name of the DBMS type, or NULL
|
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.
|
a server provider. |
|
a GdaConnection object, or NULL
|
|
a string to escape |
Returns : |
a new string suitable to use in SQL statements |
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()
.
|
a server provider. |
|
a GdaConnection object, or NULL
|
|
a string to escape |
Returns : |
a new string |