Building a new EULER module


NB : Some of the info given here is taylored to MS-Windows. It will be adapted to other OSs in the future.

Interface

The public interface of any EULER module is described in the euler\module\include\module.h file.

There are four functions. Each function is declared as WINAPI (this is a macro for FAR PASCAL in <windows.h>) call type and in extern mode (DllModule defined in <iospec.h>). The module developer has to define the _DLL_MODULE environment variable before including the iospec.h file, in order to initialize the DllModule macro.

#include <windows.h>
#include <iospec.h>
extern "C"
{
DllModule bool WINAPI moduleInit( void*& modulePt, class CmdLine* argumentPt );
DllModule bool WINAPI moduleInfo( void* modulePt );
DllModule bool WINAPI moduleRun( void* modulePt, class CMlc* an_mlc, class CmdLine* argumentPt );
DllModule bool WINAPI moduleClose( void*& modulePt );
};

bool WINAPI moduleInit( void*& modulePt, class CmdLine* argumentPt )

This function is called in the initialisation process of the EULER kernel (i.e., by the init method of a CSystem instance). It thus has to be defined for each new module. The modulePt pointer has to be set by the module developer to a unique identifier that represents one instance of the module. The argumentPt pointer is provided by the kernel to this function, to let the function retrieve all the initialisation arguments it needs. These arguments are defined in the initialisation script (.ini file) of the current system and stored in a CmdLine instance. A false return value for moduleInit aborts the initialisation process of the application.

bool WINAPI moduleInfo( void* modulePt )

This function gives information on the current module, which is typically printed in the disclaimer. It is called by the info method of a CSystem instance. This constitutes the information process of the application. The modulePt pointer is the unique identifier set in the moduleInit() function. The module developer should use this function to communicate information about the module and/or the databases files it uses or anything else (typically, legal information). The Euler kernel provides a function to display this information through the standard Euler disclaimer. A false return value for moduleInfo aborts the information process of the application.

bool WINAPI moduleRun( void* modulePt, class CMlc* an_mlc, class CmdLine* argumentPt )

This function is called in the run process of the application (i.e., by the run method of a CSystem instance). The modulePt pointer is the unique identifier set in the moduleInit() function. The argumentPt pointer is provided by the kernel to this function, to let the function retrieve all the run-time arguments (typically, command-line arguments in a command-line application). These arguments are typically used to specify the input filename, output filename, log filename, run time setup, etc. They are passed inside a CmdLine instance. A false return value stops the main run process loop of the application. The an_mlc pointer is provided to access the common working memory area of all modules in a CMlc instance.

bool WINAPI moduleClose( void*& modulePt )

This function is called in the close process (i.e. by the the close method of a CSystem instance). The modulePt pointer if the unique identifier set in the moduleInit() function and must be set to 0 ( zero or NULL ) before exiting the function. This function is typically used for deleting internal memory previously allocated by the module. If an internal error occurs, a false return value aborts the close process of the application.

Reporting errors

If an internal error occurs in any of these functions, the module developer is encouraged to display a message by throwing an exception with the Exception class. A thrown exception aborts the corresponding CSystem instance process.

 

To help you design a new module in the Microsoft Visual C++ 5 environnement, the buildNewModule.bat batch file will create a whole project for the new module you want to create and insert it into the EULER workspace you want it to belong to.

Example

Open a command window, place the prompt in the euler\tool directory and type the next command:

buildNewModule.bat syllabemodule -item Word Phoneme Syllabe -workSpace French
 

The builtNewItem.bat create the following features:

You can now open the euler.dsp or French.dsp workspace and activate the syllabemodule project. In the Header folder, edit the my_syllable.h and the my_syllable.cpp source file to insert your code. Build the syllabemodule project and your new syllabemodule is created.

You may also take a look at the EULER reference guide.


Copyright © 1999 TCTS LAB, Faculté Polytechnique de Mons, Belgium