Virtual methods for providers: GNOME Data Access 5 manual

## Virtual methods for providers

Database providers usually (that is except for virtual providers explained later) subclass the GdaServerProvider class and implement at least the mandatory virtual methods.

Virtual providers are database providers when the database engine accessed does not support SQL (or supports it poorly), such as Berkeley databases or MDB (or even LDAP). These provider's implementation's design is to create GdaDataModel data model objects and make each of them appear as a named table once the connection is opened. For example the MDB provider creates a read-only data model for each table in an MDB file and make it appear using the original table name used in MS Access (the tables cannot be modified but it is possible to use all SQLite's SQL to make SELECT queries).

Virtual providers inherit the GdaVproviderDataModel class and not the GdaServerProvider as "normal" providers do, and the number of virtual methods to implement is very limited: only the get_name(), get_version(), get_server_version(), open_connection() and get_database() should be implemented, optionnally the close_connection() can also be implemented.

## Synchronous / asynchronous mode

All the provider's commands are executed in a synchronous mode (the caller is blocked until the provider's method terminates). However some virtual methods have the a `task_id` parameter, an `async_cb` or `exec_cb` callback function pointer and a `cb_data` parameter which can be set when an asynchronous mode is required; asynchronous mode is requested if and only if the `async_cb` or `exec_cb` parmeter is not NULL.

When an asynchronous mode is requested, the method should return TRUE if it returns a boolean or NULL if it returns a pointer and set a task identifier into the `task_id` parameter if not NULL. The task identifier is passed again when the `async_cb` or `exec_cb` callback functions are called by the provider when the execution is finished.

When the provider's method terminates, it then should call the function passed as `async_cb` with the `cb_data` as last parameters.