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