GUI App: Porting an Engine for Use in a Symbian Application

The application uses the FreeBSD cksum utility as its + engine. The checksum example is an application with a user interface and an + engine written in C.

The first stage in porting this program is to split the project into + the engine (GUIAppEng) and the application (GUIApp).

The engine +

The engine is written in C. At its core is the crc() + function. This function accepts a file descriptor and returns the checksum and + the file size.

The engine's project specification file (GUIAppEng.mmp) + is as follows:

TARGET GUIAppEng.dll +TARGETTYPE dll +UID 0x1000008d 0x01000a02 +VENDORID 0x70000001 +SOURCEPATH . +SOURCE crc.c +SYSTEMINCLUDE \epoc32\include\libc \epoc32\include +LIBRARY estlib.lib euser.lib + +#if defined(WINS) + deffile GuiAppEngWINS.def +#else if defined(ARM) + deffile GuiAppEngARM.def +#endif +nostrictdef +

+ The output file is GUIAppEng.dll, whose import library + will be included by the UI. +

+ The first UID specified (0x1000008d) is the standard UID + for an interface DLL. The second UID (0x01100a02) is unique to the + GUIApp project. +

+ Splitting the project into engine and UI means that the definition of + crc() in crc.c must be marked EXPORT_C + because this function will be exported from the engine's DLL. +

+ For more information on DLLs, see DLLs. +

+Porting checksum - the GUI app +

+ The implementation of checksum (GUIApp.app) limits the + user to the selection of a single file at a time and uses the default algorithm + crc(), defined in crc.c, to produce a 32-bit value. +

+ The user interface provides two main menu commands; Calculate + checksum (invokes a file selection dialog) and View + checksums. When a file is selected and OK is pressed, the + selected file name is retrieved and opened as shown in the following code: +

+ const TUint16* fn = iFileName->PtrZ(); +int fd = wopen( ( const wchar_t* )fn, O_RDONLY, 0 ); +

+ This code fragment is taken from + examples\stdlib\GUIApp.cpp. +

+ open() returns a file descriptor which the engine's + crc() function uses to identify the file. The checksum is + calculated (unless an error occurred in attempting to open or read the file), + and is displayed. The file is closed. +

+ The file name and checksum are appended to an array, the contents of + which may be viewed by selecting View checksums. +

+ Linking to STDLIB - The project specification +

+ The application program includes several STDLIB header files, located + in \epoc32\include\libc\. At link time, the program includes + estlib.lib and the engine DLL's .lib + (GUIAppEng.lib). Unlike the previous examples, this application + does not link to ecrt0.lib. In this application there is no + main() and Symbian platform provides its own + E32Main(). +

+ For information on Symbian applications, their project specification, + and resource files, see How to build GUI applications. +

+ Some potential issues +

+
Removing writeable static
+
+ The PETRAN stage of building may report a message similar to the + following: +
+ WARNING: Dll 'SLSUMENG[0x01000a02].DLL' has initialised data. +
+ This warning, which is not reported when building for the Emulator, + indicates that the DLL contains non-const static data. This is not allowed in + ARM builds. If it is not obvious where the problem occurs, the associated + .map file + (epoc32\release\<target>\urel\<dllname>.map) contains + information which can help to track down the source file involved. A search for + from *(.bss) (to find uninitialised data) or from + *(.data) (to find initialised data) in GUIAPPEng.map will + reveal the file in which the problem occurs, and the names of the offending + variables, although static variables will not be named. +
+
Include file clashes
+
+ In C++ source files which use STDLIB routines, the Symbian platform + C++ include files must be included before any of the STDLIB files. Failure to + do this will result in the following warning: +
+ 'NULL' : macro redefinition" +
+
Mixing C and C++
+
+ C and C++ have different views about the names of functions. If you + refer to a C function from C++, ensure that its prototype is declared as + extern "C". If there are several such function declarations, it + may be more convenient to enclose them within the following: +
+ #ifdef __cplusplus +extern "C" + { + #endif + ... + #ifdef __cplusplus + } +#endif +
+ See for example examples\stdlib\GUIApp\extern.h. +
+
+
Stack usage
+
+ Some programs produce the following error: +
+ unresolved external symbol __chkstk +
+ unless the amount of stack they use is reduced. Symbian threads have + only 8k stack by default. +
+
+
Resource cleanup
+
+ Symbian platform has a requirement that all resources which were + allocated by an application must be cleaned up by the time the program + terminates. On the Emulator, in debug builds, failure to do this will cause a + panic from the __UHEAP_MARKEND macro. +
+
+ Because the data allocated in the thread-local storage for STDLIB's + DLL (the _reent structure) is not automatically cleaned up when + the environment is destroyed, it must be cleaned up by the user of STDLIB. +
+
+ The function to achieve this is CloseSTDLIB(). To use + this function, file epoc32\include\libc\sys\reent.h must be + included in the project. Call CloseSTDLIB() after the point at + which it is known that code in STDLIB's DLL will no longer be called and its + thread-local storage no longer needed. +
+
+ For example, see the destructor for CExampleDocument in + examples\stdlib\GUIApp\GUIApp.cpp. +
+ +

+ + +

+ +