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

GUI App: Porting -an Engine for Use in a Symbian ApplicationThis section describes the steps to port 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 the 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

The 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.

-DLLs - -How to build -GUI applications + + + + + +GUI +App: Porting an Engine for Use in a Symbian ApplicationThis section describes the steps to port 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 the Symbian platform provides its +own E32Main().

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

The 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.

+DLLs +

\ No newline at end of file