dico_database_module (GNU Dico Manual)

6.1 dico_database_module

Each module must export exactly one symbol of type struct dico_database_module. This symbol must be declared as

DICO_EXPORT(name, module)

where name is the name of the module file (without suffix). For example, a module word.so would have in its sourse the following declaration:

struct dico_database_module DICO_EXPORT(word, module) = {
…
};

The dico_database_module has the following members:

dico_database_module: unsigned dico_version: Interface version being used. It is recommended to use the macro DICO_MODULE_VERSION, which keeps the version number of the current interface.

dico_database_module: unsigned dico_capabilities

Module capabilities. As of version 2.10, this member can be one of the following:

DICO_CAPA_DEFAULT

This module defines a handler for a specific database format.

DICO_CAPA_NODB

This module does not handle any databases. When this capability is specified, dicod will call only the dico_init member of the structure.

This capability is used by modules defining new matching strategies or authentication methods.

Dico Callback: int dico_init (int argc, char **argv)

This callback is called right after loading the module. It is responsible for module initialization. The arguments are:

argc: Number of elements in argv.
argv: The command line given by command configuration statement (see command), split into words. The element argv[0] is the name of the module. The element argv[argc] is ‘NULL’. Word splitting follows the rules similar to those used in shell. In particular, a quoted string (using both single and double quotes) is handled as a single word.

If dico_capabilities is DICO_CAPA_DEFAULT, this method is optional. If dico_capabilities is set to DICO_CAPA_NODB, dico_init is mandatory and must be the only method defined.

Dico Callback: dico_handle_t dico_init_db (const char *db, int argc, char **argv)

Initialize the database. This method is called as a part of database initialization routine at startup of dicod, after processing dictionary configuration statement (see Databases). Its arguments are:

db: The name of the database, as given by the name statement.
argc: Number of elements in argv.
argv: The command line given by handler configuration statement (see handler). The array is ‘NULL’-terminated.

This method returns a database handle, an opaque structure identifying the database. This handle will be passed as the first argument to other methods. On error, dico_init_db shall return NULL.

Notice, that this function is not required to actually open the database, if the ‘open’ notion is supported by the underlying mechanism. Another method, dico_open is responsible for that.

Dico Callback: int dico_free_db (dico_handle_t dh)

Reclaim any resources associated with database handle dh. This method is called as part of exit cleanup routine, before the main dicod process terminates.

It shall return ‘0’ on success, or any non-‘0’ value on failure.

Dico Callback: int dico_open (dico_handle_t dh)

Open the database identified by the handle dh. This method is called as part of child process initialization routine.

It shall return ‘0’ on success, or any non-‘0’ value on failure.

The dico_open method is optional.

Dico Callback: int dico_close (dico_handle_t dh)

Close the database identified by the handle dh. This method is called as part of child process termination routine.

It shall return ‘0’ on success, or any non-‘0’ value on failure.

The dico_close method is optional, but if dico_open is defined, dico_close must be defined as well.

Dico Callback: char * dico_db_info (dico_handle_t dh)

Return a database information string for the database identified by dh. This function is called on each SHOW INFO command, unless an informational text for this database is supplied in the configuration file (see info). This value must be allocated using malloc(3). The caller is responsible for freeing it when no longer needed.

This method is optional.

Dico Callback: char * dico_db_descr (dico_handle_t dh)

Return a short database description string for the database identified by dh. This function is called on each SHOW DB command, unless a description for this database is supplied in the configuration file (see descr). This value must be allocated using malloc(3). The caller is responsible for freeing it when no longer needed.

This method is optional.

Dico Callback: dico_result_t dico_match (dico_handle_t dh, const dico_strategy_t strat, const char *word)

Use the strategy strat to search in the database dh, and return all headwords matching word.

This method returns a result handle, an opaque pointer that can then be used to display the obtained results. It returns NULL if no matches were found.

Dico Callback: dico_result_t dico_define (dico_handle_t dh, const char *word)

Find definitions of headword word in the database identified by dh.

This method returns a result handle, an opaque pointer that can then be used to display the obtained results. It returns NULL if no matches were found.

Dico Callback: int dico_output_result (dico_result_t rp, size_t n, dico_stream_t str)

The dico_output_result method outputs to stream str the nth result from result set rp. The latter is a result handle, obtained from a previous call to dico_match or dico_define.

Returns ‘0’ on success, or any non-‘0’ value on failure.

It is guaranteed that the dico_output_result callback is called as many times as there are elements in rp (as determined by the dico_result_count callback, described below) and that for each subsequent call the value of n equals its value from the previous call incremented by one.

At the first call n equals 0.

Dico Callback: size_t dico_result_count (dico_result_t rp): Return the number of distinct elements in the result set identified by rp. The latter is a result handle, obtained from a previous call to dico_match or dico_define.

Dico Callback: size_t dico_compare_count (dico_result_t rp)

Return the number of comparisons performed when constructing the result set identified by rp.

This method is optional.

Dico Callback: void dico_free_result (dico_result_t rp): Free any resources used by the result set rp, which is a result handle, obtained from a previous call to dico_match or dico_define.

Dico Callback: int dico_result_headers (dico_result_t rp, dico_assoc_list_t hdr): Populate associative list hdr with the headers describing result set rp. This callback is optional. If defined, it will be called before outputting the result set rp if OPTION MIME is in effect (see OPTION MIME).

Dico Callback: int dico_run_test (int argc, char **argv): Runs unit tests for the module. Argument vector contains all command line arguments that follow the --runtest option, up to the ‘--’ marker or end of line, whichever is encountered first.