+/** \brief Get version of the module.
+ *
+ * Each module (dictionary engine) shoul keep its version number. It could be
+ * accessed by this function.
+ * \Warning Module version and Engine API version are not the same !
+ * \param module module which version we want to get
+ * \return string containing version of given module
+ */
+#define dict_eng_module_get_version(module)\
+ ((module).engine_version())
+
+/** \brief 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.
+ * \Warning Module version and Engine API version are not the same !
+ * \param module module which supported API version we want to get
+ * \return string containing version of engine API given module was compiled
+ * with
+ */
+#define dict_eng_module_get_api_version(module)\
+ ((module).engine_api_version())
+
+/** \brief Get format of supported dictionaries.
+ *
+ * Call this function to get description of supported dictionary format.
+ * \param module module which supported format we want to know
+ * \return string describing supported format (e.g. XDXF, StarDict)
+ * with
+ */
+#define dict_eng_module_get_format(module)\
+ ((module).engine_format())
+
+/** \brief Create engine instance connected with particular dictionary.
+ *
+ * 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.
+ * \param module module which we want to use to handle dictionary
+ * \param location path to dictionary file
+ * \param flags define if we want to optimize dictionary
+ * \return pointer to Engine structure connected with dictionary or NULL if
+ * creating failed.
+ */
+#define dict_eng_module_create(module, location, flags)\
+ ( (module).engine_create((location),\
+ (flags),\
+ NULL,\
+ NULL,\
+ 0.01) )
+
+/** \brief Create engine instance connected with particular dictionary.
+ *
+ * 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.
+ * \param module module which we want to use to handle dictionary
+ * \param location path to dictionary file
+ * \param flags define if we want to optimize dictionary
+ * \param progress_handler callback for progress bar
+ * \param progress_data pointer to data which will be passed to progress_handler
+ * \param seed defines how often will be progress_handler called (0.01 means
+ * that progress_handler will be called at each 1% of progress)
+ * \return pointer to Engine structure connected with dictionary or NULL if
+ * creating failed.
+ * \see cb_progress
+ */
+#define dict_eng_module_create_ext(module, location, flags, progress_handler,\
+ progress_data, seed)\
+ ( (module).engine_create((location),\
+ (flags),\
+ (progress_handler),\
+ (progress_data),\
+ (seed)) )
+/*@}*/
+
+/** \name 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.
+ * \see Engine
+ */
+/*@{*/
+
+
+/** \brief Set seed value for particular progress callback.
+ *
+ * While engine is working it is possible to call progress callback sometimes.
+ * Seed define after how big progress such a calback will be called.
+ * \param engine pointer to engine (particular dictionary)
+ * \param signal signal for which we want to set a seed
+ * \param val progress step for progress callback
+ */
+#define dict_eng_set_progress_seed(engine, signal, val)\
+ ((engine)->engine_set_progress_seed( (engine),\
+ (signal),\
+ (val) ))
+
+/** \brief 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.
+ * \param engine pointer to engine (particular dictionary)
+ * \param state boolean value deciding if auto-freeing shoul be enabled
+ */
+#define dict_eng_set_auto_free(engine, state)\
+ (engine)->engine_set_auto_free((engine), (state))
+
+/** \brief 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.
+ *
+ * \param engine pointer to engine which should be optimized
+ * \see dict_eng_module_create() | dict_eng_is_optimized() | Engine
+ */
+#define dict_eng_optimize(engine) ((engine)->engine_optimize((engine)))
+
+/** \brief Find out if specified engine is using optimization now.
+ *
+ * \param engine pointer to engine
+ * \return boolean value telling if particular dictionary is optimized at this
+ * moment
+ */
+#define dict_eng_is_optimized(engine) ((engine)->engine_is_optimized((engine)))
+
+/** \brief 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.
+ * \param engine pointer to the engine
+ * \return gchar* containing path to dictionary path
+ * \see dict_eng_module_create | dict_eng_module_create_ext
+ */
+#define dict_eng_get_location(engine) ((engine)->engine_location((engine)))
+
+/** \brief 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.
+ * \param engine pointer to the engine
+ * \return EngineStatus defining finish code of last operation
+ * \see EngineStatus | dict_eng_status_message
+ */
+#define dict_eng_get_last_status(engine) ((engine)->engine_status((engine)))
+
+/** \brief 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.
+ * \param engine pointer to the engine
+ * \param error code which we want to translate
+ * \return gchar* message describing concrete error code
+ * \see EngineStatus | dict_eng_get_last_status
+ */
+#define dict_eng_status_message(engine, status)\
+ ((engine)->engine_status_message((status)))
+
+/** \brief 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().
+ *
+ * \param engine pointer to the engine which is not needed anymore
+ * \see dict_eng_module_create | Engine
+ */
+#define dict_eng_destroy(engine) ((engine)->engine_close(engine))
+
+/** \brief Start searching for words matching given pattern.
+ *
+ * \param engine pointer to the engine to search in
+ * \param pattern string describing pattern to search
+ * \param 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
+ * \see dict_eng_search_word_translation | Engine
+ */
+#define dict_eng_search_word_list(engine, pattern, data)\
+ ((engine)->engine_search_word_list( (engine),\
+ (pattern),\
+ (data) ))
+
+/** \brief Start searching for word's translation.
+ *
+ * \param engine pointer to the engine to search in
+ * \param word word which translation we are searching
+ * \param 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
+ * \see dict_eng_search_word_list | Engine
+ */
+#define dict_eng_search_word_translation(engine, word, data)\
+ ((engine)->engine_search_word_translation( (engine),\
+ (word),\
+ (data) ))
+
+/** \brief Set callback function for particular signal.
+ *
+ * \param engine pointer to the engine
+ * \param signal defines for what signal we are setting callback
+ * \param c_handler function which will be called on signal
+ * \param data pointer to data which will be passed to c_handler. It could be
+ * overwritten while starting search
+ * \return gpointer to the previously set callback
+ * \see dict_eng_search_word_list | dict_eng_search_word_translation | Engine
+ */
+#define dict_eng_set_callback(engine, signal, c_handler, data)\
+ ((engine)->engine_set_callback( (engine),\
+ (signal),\
+ (c_handler),\
+ (data) ))
+
+/** \brief Add new word to the dictionary.
+ *
+ * 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.
+ *
+ * \param engine pointer to the engine
+ * \param word string with word which we want to add
+ * \param tran string containing translation of word
+ * \return boolean telling if word has been added. FALSE value could be returned
+ * for few reasons: engine do not support adding word, word already exists in
+ * dictionary etc.
+ */
+#define dict_eng_add_word(engine,word,tran)\
+ ((engine)->engine_add_word( (engine),\
+ (word),\
+ (tran) ))
+
+
+/** \brief Remove word from the dictionary.
+ *
+ * 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.
+ *
+ * \param engine pointer to the engine
+ * \param word string with word which we want to remove
+ * \return boolean telling if word has been removed. FALSE value could be
+ * returned for few reasons: engine do not support adding word, word already
+ * exists in dictionary etc.
+ */
+#define dict_eng_remove_word(engine,word)\
+ ((engine)->engine_remove_word( (engine),\
+ (word) ))
+
+/** \brief Get language from which this dictionary translates.
+ *
+ * Method returns language description from which given dictionary engine
+ * translates.
+ *
+ * \param engine pointer to the engine
+ * \return string describing language
+ * \sa dict_eng_get_lang_to
+ */
+#define dict_eng_get_lang_from(engine) ((engine)->engine_get_lang_from(engine))
+
+/** \brief Get language to which this dictionary translates.
+ *
+ * Method returns language description to which given dictionary engine
+ * translates.
+ *
+ * \param engine pointer to the engine
+ * \return string describing language
+ * \sa dict_eng_get_lang_from
+ */
+#define dict_eng_get_lang_to(engine) ((engine)->engine_get_lang_to(engine))
+
+/** \brief 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.
+ *
+ * \param engine pointer to the engine
+ * \return string containing dictionary title
+ * \sa dict_eng_get_lang_from | dict_eng_get_lang_to
+ */
+#define dict_eng_get_title(engine) ((engine)->engine_get_title(engine))
+
+/** \brief 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.
+ *
+ * \param engine pointer to the engine
+ * \return string containing path to icon
+ */
+#define dict_eng_get_icon_path(engine) ((engine)->engine_get_icon_path(engine))
+/*@}*/
+
+/** \name 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.
+ */
+/*@{*/
+
+/** \brief 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.
+ * \note Programmers must not use value of ENGINE_WORD_LIST_SIGNAL
+ * directly!
+ * \see cb_word_list | dict_eng_set_callback | dict_eng_search_word_list |
+ * ENGINE_WORD_TRANSLATION_SIGNAL
+ */