Assembling all the parts: GNOME Data Access 5 manual

## Assembling all the parts

A database provider is in fact a shared library which is loaded when Libgda is initialized. The skeleton implementations in `providers/skel-implementation` propose the following files layout (some of the files are not required for virtual providers).

Of course this files layout is not required, but make it easy for maintenance. In the following list, the filenames here are the one for the "Capi" provider, and each provider should rename them:

- `gda-capi.h`: contains the provider name, the include files necessary to use the API and the declaration of the provider's specific connection data

- `gda-capi-provider.[ch]`: are the header and implementation files for the object inheriting the GdaServerProvider object. This object must implement its virtual methods.

- `gda-capi-recordset.[ch]`: are the header and implementation files for the object inheriting the GdaDataSelect object. This object must implement its virtual methods.

- `gda-capi-ddl.[ch]`: are the files implementing the DDL queries

- `gda-capi-parser.[ch]`: are the header and implementation files for the object implementing a specific parser, inheriting GdaSqlParser, see the PostgreSQL provider's implementation for example.

- `gda-capi-pstmt.[ch]`: are the header and implementation files for the object representing prepared statement and inheriting GdaPStmt

- `gda-capi-blob-op.[ch]`: are the header and implementation files for the object inheriting the GdaBlopOp object. This object must implement its virtual methods.

- `gda-capi-meta.[ch]`: are the files where the meta-data information extraction is implemented.

- `libmain.c`: file to make it possible for Libgda to identify the provider.

- `capi_specs_dsn.xml.in`: file where the connection parameters are described, before being translated

- `libgda-capi-5.0.pc.in`: file to be used by pkg-config to identify the provider, before being computed by the configure script.

- other .xml.in files: DDL queries' parameters, before translation

## libmain.c

Once the shared library implementing the provider is loaded (and all the necessary dependencies are also loaded), Libgda tries to locate some functions to identify the provider (if any of these function is missing, then the DLL is unloaded and the provider is not availaibe).

The skeleton implementations in `providers/skel-implementation` propose to implement those functions in a `libmain.c` file. The functions are the following ones:

### plugin_init()

This function initializes the plugin; it has a single argument which is the path where the provider is. As the module can be unloaded, any static data allocated here must be freed when the module is unloaded, in a g_module_unload() function. If the module must not be unloaded, it must be made resident using g_module_make_resident(), in a g_module_check_init() function

Note that after a GdaServerProvider object has been created (ie after plugin_create_provider() has been called once), the module will not be unloaded anymore.

### plugin_get_name()

This funtion returns the name of the provider, it must return the same string as what the get_name()'s provider's virtual method returns.

### plugin_get_description()

This funtion returns a description of the provider.

### plugin_get_dsn_spec()

This function returns a description of the parameters which have or can be set when opening a connection. This description uses an XML syntax and is usually stored in a separate XML file (for easier translation).

Here is an example, when only one "DB_NAME" parameter is required:

    <?xml version="1.0"?>
    <data-set-spec>
      <parameters>
        <parameter id="DB_NAME" _name="Database name" _descr="The name of a database to use" gdatype="gchararray" nullok="FALSE"/>
      </parameters>
    </data-set-spec>

Note that the the attributes which have a name starting with an underscore should be translated (see the `Makefile.am` file for some example on ho this is done).

### plugin_get_auth_spec()

This function returns a description of the authentication information required by the provider. If the only information is a username/password pair, then it is not necessary to implement that function.

However, if a username is required, then it must be name "USERNAME", and if a password is required, it must be named "PASSWORD".

### plugin_create_provider()

This function actually instantiates a provider object and returns it.