Data Structures | |
struct | _Engine |
Structure describing particular dictionary. More... | |
struct | EngineModule |
Global functions structure. More... | |
Flags and Error Codes | |
enum | EngineOptimizationFlag { ENGINE_CREATE = 1 << 0, ENGINE_NO = 1 << 1, ENGINE_REFRESH = 1 << 2 } |
Flags defining how to use optimization for particular dictionary. More... | |
enum | EngineStatus { ENGINE_NO_ERROR = 0, ENGINE_WRONG_FILE = 1 << 0, ENGINE_COULDNT_READ = 1 << 1, ENGINE_COULDNT_WRITE = 1 << 2, ENGINE_INTERNAL_ERROR = 1 << 3, ENGINE_NO_FILE = 1 << 4, ENGINE_OUT_OF_MEMORY = 1 << 5 } |
Codes of possible errors which can occure while engine is working. More... | |
Callbacks' Types | |
Types defining of what types should be particular callbacks to properly work with Engine API.
| |
typedef void(*) | cb_word_list (GArray *list, gchar *pattern, gpointer user_data, EngineStatus error) |
Type of callback functions for retrieving word list. | |
typedef void(*) | cb_word_translation (gchar *translation, gchar *word, gpointer user_data, EngineStatus error) |
Type of callback functions for retrieving word's translation. | |
typedef void(*) | cb_progress (gdouble value, gpointer user_data, EngineStatus error) |
Type of callback functions for handling progress of optimization. | |
Names and Versions | |
These defines how should be called exported function and what is the version of this Engine API. | |
#define | ENGINE_API_VERSION "1.0.0" |
ENGINE_API_VERSION tells what version of API this header define. | |
#define | _GLOBAL_FUNCTIONS_ engine_global_functions |
Global functions structure name. | |
#define | GLOBAL_FUNCTIONS_NAME __TOSTRING(_GLOBAL_FUNCTIONS_) |
String containing global functions structure name. | |
Global Module Macros | |
These macros can be used to make it easier to work with many dictionary engine modules. | |
#define | dict_eng_module_check(module, location) ((module).engine_check(location)) |
Checks if given path points to dictionary is in compatible format. | |
#define | dict_eng_module_get_description(module) ((module).engine_description()) |
Get description of the module. | |
#define | dict_eng_module_get_version(module) ((module).engine_version()) |
Get version of the module. | |
#define | dict_eng_module_get_api_version(module) ((module).engine_api_version()) |
Get version of Engine API with which module was compiled. | |
#define | dict_eng_module_get_format(module) ((module).engine_format()) |
Get format of supported dictionaries. | |
#define | dict_eng_module_create(module, location, flags) |
Create engine instance connected with particular dictionary. | |
#define | dict_eng_module_create_ext(module, location, flags, progress_handler, progress_data, seed) |
Create engine instance connected with particular dictionary. | |
Particular Dictionary Macros | |
These macros are working on particular dictionary. It makes it easier to work through these macros than by calling member of engine structure.
| |
#define | dict_eng_set_progress_seed(engine, signal, val) |
Set seed value for particular progress callback. | |
#define | dict_eng_set_auto_free(engine, state) (engine)->engine_set_auto_free((engine), (state)) |
Set-up auto-freeing of memory allocated by engine. | |
#define | dict_eng_optimize(engine) ((engine)->engine_optimize((engine))) |
Activate optimization mechanizms for particular dictionary. | |
#define | dict_eng_is_optimized(engine) ((engine)->engine_is_optimized((engine))) |
Find out if specified engine is using optimization now. | |
#define | dict_eng_get_location(engine) ((engine)->engine_location((engine))) |
To get know from what location was created current dictionary. | |
#define | dict_eng_get_last_status(engine) ((engine)->engine_status((engine))) |
Tells if last operation was sucesfull. | |
#define | dict_eng_status_message(engine, status) ((engine)->engine_status_message((status))) |
Translate pure state code to meaningfull message. | |
#define | dict_eng_destroy(engine) ((engine)->engine_close(engine)) |
Destroy gently and completely given dictionary engine. | |
#define | dict_eng_search_word_list(engine, pattern, data) |
Start searching for words matching given pattern. | |
#define | dict_eng_search_word_translation(engine, word, data) |
Start searching for word's translation. | |
#define | dict_eng_set_callback(engine, signal, c_handler, data) |
Set callback function for particular signal. | |
#define | dict_eng_add_word(engine, word, tran) |
Add new word to the dictionary. | |
#define | dict_eng_remove_word(engine, word) |
Remove word from the dictionary. | |
#define | dict_eng_get_lang_from(engine) ((engine)->engine_get_lang_from(engine)) |
Get language from which this dictionary translates. | |
#define | dict_eng_get_lang_to(engine) ((engine)->engine_get_lang_to(engine)) |
Get language to which this dictionary translates. | |
#define | dict_eng_get_title(engine) ((engine)->engine_get_title(engine)) |
Get dictionary title. | |
#define | dict_eng_get_icon_path(engine) ((engine)->engine_get_icon_path(engine)) |
Get dictionary icon path. | |
Callbacks' Signals | |
These strings identify signals which will be emitted after dictionary engine finished some work.
Signals are defined as a strings to make it easier to keep compatibility and to be more flexible for future changes. | |
#define | ENGINE_WORD_LIST_SIGNAL "on_word_list_found" |
Signals that words list matching for given pattern is available. | |
#define | ENGINE_WORD_TRANSLATION_SIGNAL "on_word_translation_found" |
Signals that translation is available for given word. | |
#define | ENGINE_PROGRESS_OPTIMIZING_SIGNAL "on_progress_optimizing" |
Signals progress event for optimization proccess. | |
Typedefs | |
typedef _Engine | Engine |
typedef EngineModule(*) | getting_additional_t (void) |
Functions | |
EngineModule | engine_global_functions (void) |
Get structure and access to all module functions. |
This file define engine API which should be implemented by each dictionary and is being used by WhiteStork manager (or any other program that want to use WhiteStork plug-in capabilities).
#define _GLOBAL_FUNCTIONS_ engine_global_functions |
Global functions structure name.
This name defines what should be called function used for getting global functions structure. It helps in dynamical loading of particular engine.
When writing new engine, there should be always function called like this and returning particular EngineModule structure.
Definition at line 91 of file dictionary_engine.h.
#define dict_eng_add_word | ( | engine, | |||
word, | |||||
tran | ) |
Value:
((engine)->engine_add_word( (engine),\ (word),\ (tran) ))
This method should be implemented by every engine, but it is in API only for bookmark engine. Other enignes should do nothing but return FALSE.
engine | pointer to the engine | |
word | string with word which we want to add | |
tran | string containing translation of word |
Definition at line 386 of file dictionary_engine.h.
Referenced by ws_mng_add_bookmark().
#define dict_eng_destroy | ( | engine | ) | ((engine)->engine_close(engine)) |
Destroy gently and completely given dictionary engine.
When user do not need anymore particular dictionary, he must destroy it to free memory allocated by this dictionary. It will close every opened file descriptor, free any additional memory block allocated while engine was working etc. User are not allowed to call free() on dictionary without calling before dict_eng_destroy().
engine | pointer to the engine which is not needed anymore |
Definition at line 328 of file dictionary_engine.h.
Referenced by ws_mng_close(), and ws_mng_signal_handling().
#define dict_eng_get_icon_path | ( | engine | ) | ((engine)->engine_get_icon_path(engine)) |
Get dictionary icon path.
Some dictionaries have own icons, which could be used in UI. If such a icon exists, this function should return path to it. Otherwise it should return path to the default icon.
engine | pointer to the engine |
Definition at line 449 of file dictionary_engine.h.
#define dict_eng_get_lang_from | ( | engine | ) | ((engine)->engine_get_lang_from(engine)) |
Get language from which this dictionary translates.
Method returns language description from which given dictionary engine translates.
engine | pointer to the engine |
Definition at line 416 of file dictionary_engine.h.
#define dict_eng_get_lang_to | ( | engine | ) | ((engine)->engine_get_lang_to(engine)) |
Get language to which this dictionary translates.
Method returns language description to which given dictionary engine translates.
engine | pointer to the engine |
Definition at line 427 of file dictionary_engine.h.
#define dict_eng_get_last_status | ( | engine | ) | ((engine)->engine_status((engine))) |
Tells if last operation was sucesfull.
If user want to be sure that everything was ok, during last operation (it has finished with success), he has to check if dict_eng_get_last_status() is equal to ENGINE_NO_ERROR. If not, he can also find the reason why operation failed.
engine | pointer to the engine |
Definition at line 303 of file dictionary_engine.h.
#define dict_eng_get_location | ( | engine | ) | ((engine)->engine_location((engine))) |
To get know from what location was created current dictionary.
If user of engine want to get know from what locatione exactly was created particular engine, he could call this function. It returns string, most likely the same as the one passed earlier to dict_eng_module_create() function as a location argument.
engine | pointer to the engine |
Definition at line 291 of file dictionary_engine.h.
#define dict_eng_get_title | ( | engine | ) | ((engine)->engine_get_title(engine)) |
Get dictionary title.
Each dictionary has title describing data in it, its sources etc. This function returns this title which could be used in UI for the end user.
engine | pointer to the engine |
Definition at line 438 of file dictionary_engine.h.
#define dict_eng_is_optimized | ( | engine | ) | ((engine)->engine_is_optimized((engine))) |
Find out if specified engine is using optimization now.
engine | pointer to engine |
Definition at line 279 of file dictionary_engine.h.
#define dict_eng_module_check | ( | module, | |||
location | ) | ((module).engine_check(location)) |
Checks if given path points to dictionary is in compatible format.
If there is no knowledge what format dictionary has, it is possible to check if particular engine will handle given dictionary.
module | module which compatibility we want to check | |
location | dictionary which compatibility with module we want to check |
Definition at line 131 of file dictionary_engine.h.
Referenced by ws_mng_load_bookmark(), and ws_mng_load_dict().
#define dict_eng_module_create | ( | module, | |||
location, | |||||
flags | ) |
Value:
( (module).engine_create((location),\ (flags),\ NULL,\ NULL,\ 0.01) )
It is simplified version of macro dict_eng_module_create_ext. It do the same, the only difference is that it takes less number of parameter and disable progress_handler while function is working.
module | module which we want to use to handle dictionary | |
location | path to dictionary file | |
flags | define if we want to optimize dictionary |
Definition at line 193 of file dictionary_engine.h.
#define dict_eng_module_create_ext | ( | module, | |||
location, | |||||
flags, | |||||
progress_handler, | |||||
progress_data, | |||||
seed | ) |
Value:
( (module).engine_create((location),\ (flags),\ (progress_handler),\ (progress_data),\ (seed)) )
To start using particular dictionary it is required to create concrete instance of engine structure, connected with that dictionary (file). This function allow to create such a structure. In addition to this, this function set a callback for caching progress bar, while this proccess take place before final engine structure is created. Setting other callbacks is possible only after this function finished.
module | module which we want to use to handle dictionary | |
location | path to dictionary file | |
flags | define if we want to optimize dictionary | |
progress_handler | callback for progress bar | |
progress_data | pointer to data which will be passed to progress_handler | |
seed | defines how often will be progress_handler called (0.01 means that progress_handler will be called at each 1% of progress) |
Definition at line 220 of file dictionary_engine.h.
Referenced by ws_mng_load_bookmark(), and ws_mng_load_dict().
#define dict_eng_module_get_api_version | ( | module | ) | ((module).engine_api_version()) |
Get version of Engine API with which module was compiled.
Use this function to get know which version of Engine API this particular engine support.
module | module which supported API version we want to get |
Definition at line 169 of file dictionary_engine.h.
#define dict_eng_module_get_description | ( | module | ) | ((module).engine_description()) |
Get description of the module.
If user would like to present some information about particular module, he can use this function. It returns string (char*) that should contain basic information about module (engine). It could return, for example, something similiar to:
"XDXF Engine Module. Copyright (C) 2007, foo. Version 1.0"
module | module which description we want to get |
Definition at line 146 of file dictionary_engine.h.
#define dict_eng_module_get_format | ( | module | ) | ((module).engine_format()) |
Get format of supported dictionaries.
Call this function to get description of supported dictionary format.
module | module which supported format we want to know |
Definition at line 179 of file dictionary_engine.h.
#define dict_eng_module_get_version | ( | module | ) | ((module).engine_version()) |
Get version of the module.
Each module (dictionary engine) shoul keep its version number. It could be accessed by this function.
module | module which version we want to get |
Definition at line 157 of file dictionary_engine.h.
#define dict_eng_optimize | ( | engine | ) | ((engine)->engine_optimize((engine))) |
Activate optimization mechanizms for particular dictionary.
Every engine could have some optimization methods. By calling this function we enabled this option. For the user of the engine it is not important what kind of optimization is used in current engine, how does it work etc. It should be opaque for engine's users.
engine | pointer to engine which should be optimized |
Definition at line 271 of file dictionary_engine.h.
#define dict_eng_remove_word | ( | engine, | |||
word | ) |
Value:
((engine)->engine_remove_word( (engine),\ (word) ))
This method should be implemented by every engine, but it is in API only for bookmark engine. Other enignes should do nothing but return FALSE.
engine | pointer to the engine | |
word | string with word which we want to remove |
Definition at line 403 of file dictionary_engine.h.
Referenced by ws_mng_remove_bookmark().
#define dict_eng_search_word_list | ( | engine, | |||
pattern, | |||||
data | ) |
Value:
((engine)->engine_search_word_list( (engine),\ (pattern),\ (data) ))
engine | pointer to the engine to search in | |
pattern | string describing pattern to search | |
data | pointer do data which should be passed to callback function after searching has been completed. If it is NULL, plugin will use data pointer given while setting callback function for searching words list |
Definition at line 339 of file dictionary_engine.h.
Referenced by ws_mng_search_word().
#define dict_eng_search_word_translation | ( | engine, | |||
word, | |||||
data | ) |
Value:
((engine)->engine_search_word_translation( (engine),\ (word),\ (data) ))
engine | pointer to the engine to search in | |
word | word which translation we are searching | |
data | pointer do data which should be passed to callback function after searching has been completed. If it is NULL, plugin will use data pointer given while setting callback function for searching translation |
Definition at line 353 of file dictionary_engine.h.
Referenced by ws_mng_search_translation().
#define dict_eng_set_auto_free | ( | engine, | |||
state | ) | (engine)->engine_set_auto_free((engine), (state)) |
Set-up auto-freeing of memory allocated by engine.
Auto-freeing mechanism allows user to not thinking about memory chunks allocated by engine. If it is enabled user do not need to free received GArray with words or translation in callback functions.
engine | pointer to engine (particular dictionary) | |
state | boolean value deciding if auto-freeing shoul be enabled |
Definition at line 258 of file dictionary_engine.h.
#define dict_eng_set_callback | ( | engine, | |||
signal, | |||||
c_handler, | |||||
data | ) |
Value:
((engine)->engine_set_callback( (engine),\ (signal),\ (c_handler),\ (data) ))
engine | pointer to the engine | |
signal | defines for what signal we are setting callback | |
c_handler | function which will be called on signal | |
data | pointer to data which will be passed to c_handler. It could be overwritten while starting search |
Definition at line 368 of file dictionary_engine.h.
Referenced by ws_mng_load_bookmark(), and ws_mng_load_dict().
#define dict_eng_set_progress_seed | ( | engine, | |||
signal, | |||||
val | ) |
Value:
((engine)->engine_set_progress_seed( (engine),\ (signal),\ (val) ))
While engine is working it is possible to call progress callback sometimes. Seed define after how big progress such a calback will be called.
engine | pointer to engine (particular dictionary) | |
signal | signal for which we want to set a seed | |
val | progress step for progress callback |
Definition at line 245 of file dictionary_engine.h.
#define dict_eng_status_message | ( | engine, | |||
status | ) | ((engine)->engine_status_message((status))) |
Translate pure state code to meaningfull message.
If there was a error during engine was working, we can present to the user the reason for this error in meaningfull form.
engine | pointer to the engine | |
error | code which we want to translate |
Definition at line 314 of file dictionary_engine.h.
#define ENGINE_API_VERSION "1.0.0" |
ENGINE_API_VERSION tells what version of API this header define.
Numbers in version are:
Definition at line 81 of file dictionary_engine.h.
#define ENGINE_PROGRESS_OPTIMIZING_SIGNAL "on_progress_optimizing" |
Signals progress event for optimization proccess.
ENGINE_PROGRESS_OPTIMIZING_SIGNAL defines name for signal passed to dict_eng_set_callback() function as a signal parameter. Function set to handle this signal should be called only while creating cache files and other resources needed for optimization. This function should have cb_word_translation type.
Definition at line 499 of file dictionary_engine.h.
Referenced by bm_engine_set_callback(), bm_engine_set_progress_seed(), xdxf_engine_set_callbacks(), and xdxf_engine_set_progress_seed().
#define ENGINE_WORD_LIST_SIGNAL "on_word_list_found" |
Signals that words list matching for given pattern is available.
ENGINE_WORD_LIST_SIGNAL defines name for signal passed to dict_eng_set_callback() function as a signal parameter. Function set to handle this signal should be called only from dict_eng_search_word_list() and have cb_word_list type.
Definition at line 473 of file dictionary_engine.h.
Referenced by bm_engine_set_callback(), ws_mng_load_bookmark(), ws_mng_load_dict(), and xdxf_engine_set_callbacks().
#define ENGINE_WORD_TRANSLATION_SIGNAL "on_word_translation_found" |
Signals that translation is available for given word.
ENGINE_WORD_TRANSLATION_SIGNAL defines name for signal passed to dict_eng_set_callback() function as a signal parameter. Function set to handle this signal should be called only from dict_eng_search_word_translation() and have cb_word_translation
Definition at line 486 of file dictionary_engine.h.
Referenced by bm_engine_set_callback(), ws_mng_load_bookmark(), ws_mng_load_dict(), and xdxf_engine_set_callbacks().
#define GLOBAL_FUNCTIONS_NAME __TOSTRING(_GLOBAL_FUNCTIONS_) |
String containing global functions structure name.
This string contains GLOBAL_FUNCTIONS name. It should be used while trying to load global functions structure. It could look like this:
getting_additional_t get_functions; GModule *library = g_module_open("/path/to/module", G_MODULE_BIND_LAZY); (...) g_module_symbol(library, GLOBAL_FUNCTIONS_NAME, (gpointer)&get_functions);
Definition at line 112 of file dictionary_engine.h.
Referenced by ws_mng_init().
typedef void(*) cb_progress(gdouble value, gpointer user_data, EngineStatus error) |
Type of callback functions for handling progress of optimization.
Function which is set by dict_eng_set_callback() to signal ENGINE_PROGRESS_OPTIMIZING_SIGNAL should be exactly this type.
value | number telling what percentage (0.00 - 1.00) of optimization proccess is finished. | |
error | error code; if everything was ok it is ENGINE_NO_ERROR | |
user_data | pointer to data set by user to be passing to each callback for ENGINE_PROGRESS_OPTIMIZING_SIGNAL signal |
Definition at line 606 of file dictionary_engine.h.
typedef void(*) cb_word_list(GArray *list, gchar *pattern, gpointer user_data, EngineStatus error) |
Type of callback functions for retrieving word list.
Function which is set by dict_eng_set_callback() to signal ENGINE_WORD_LIST_SIGNAL should be exactly this type.
list | GArray with all words matching given pattern | |
pattern | string containing pattern for words | |
error | error code; if everything was ok it is ENGINE_NO_ERROR | |
user_data | pointer to data set by user to be passing to each callback for ENGINE_WORD_LIST_SIGNAL signal |
Definition at line 574 of file dictionary_engine.h.
typedef void(*) cb_word_translation(gchar *translation, gchar *word, gpointer user_data, EngineStatus error) |
Type of callback functions for retrieving word's translation.
Function which is set by dict_eng_set_callback() to signal ENGINE_WORD_TRANSLATION_SIGNAL should be exactly this type.
translation | translation of given word | |
word | word which translation we already retrieved | |
error | error code; if everything was ok it is ENGINE_NO_ERROR | |
user_data | pointer to data set by user to be passing to each callback for ENGINE_WORD_TRANSLATION_SIGNAL signal |
Definition at line 590 of file dictionary_engine.h.
Flags defining how to use optimization for particular dictionary.
This flags are used while calling dict_eng_module_create_ext and dict_eng_module_create functions. After instance of engine was created it is possible to enable optimization by function dict_eng_optimize.
ENGINE_CREATE | use optimization. If cache file does not exist - create it. |
ENGINE_NO | disables optimization at all |
ENGINE_REFRESH | always recreate cache file and use optimization |
Definition at line 513 of file dictionary_engine.h.
00514 { 00515 ENGINE_CREATE = 1 << 0, 00517 ENGINE_NO = 1 << 1, 00519 ENGINE_REFRESH = 1 << 2 00521 } EngineOptimizationFlag;
enum EngineStatus |
Codes of possible errors which can occure while engine is working.
Enum type for errors' codes. One of this code is always in last error variable (variable 'last error' is invisible for programmers - they should use function dict_eng_get_last_status() and optionally dict_eng_get_status_message() to get know what kind of error occured).
Definition at line 531 of file dictionary_engine.h.
00532 { 00533 ENGINE_NO_ERROR = 0, 00535 ENGINE_WRONG_FILE = 1 << 0, 00538 ENGINE_COULDNT_READ = 1 << 1, 00541 ENGINE_COULDNT_WRITE = 1 << 2, 00544 ENGINE_INTERNAL_ERROR = 1 << 3, 00546 ENGINE_NO_FILE = 1 << 4, 00548 ENGINE_OUT_OF_MEMORY = 1 << 5 00550 }
EngineModule engine_global_functions | ( | void | ) |
Get structure and access to all module functions.
Definition at line 992 of file engine_bookmark.c.
References bm_engine_check(), bm_engine_create(), bm_engine_description(), bm_engine_format(), bm_engine_version(), EngineModule::engine_check, EngineModule::engine_create, EngineModule::engine_description, EngineModule::engine_format, EngineModule::engine_version, and LOGS.
00993 { 00994 LOGS("Bookmark/%s->%s() called.\n",(gchar*)__FILE__,(gchar*)__FUNCTION__); 00995 EngineModule result; 00996 result.engine_check = bm_engine_check; 00997 result.engine_description = bm_engine_description; 00998 result.engine_format = bm_engine_format; 00999 result.engine_version = bm_engine_version; 01000 result.engine_create = bm_engine_create; 01001 LOGS("Bookmark/%s->%s()returned EngineModule at adress=%p.\n", 01002 (gchar*)__FILE__, 01003 (gchar*)__FUNCTION__, 01004 &result 01005 ); 01006 return result; 01007 }