Dico |
|
GNU Dictionary Server |
Sergey Poznyakoff |
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 thedico_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 elementargv[0]
is the name of the module. The elementargv[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
isDICO_CAPA_DEFAULT
, this method is optional. Ifdico_capabilities
is set toDICO_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 processingdictionary
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 returnNULL
.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 ifdico_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 todico_match
ordico_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 thedico_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
ordico_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
ordico_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.
This document was generated on September 4, 2020 using makeinfo.
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.