The WINS platform

The Emulator is the primary development environment for the Symbian platform. Programs are initially developed under the Emulator and are then ported to their target platform.

The Emulator runs in a single process environment, known as WINS. This section details the differences between this environment, and the ARMI, ARM4, THUMB environments used in real Symbian devices.

The S in WINS stands for "single process". WINS supports multiple threads, but only a single process. This causes slight differences between WINS and target machines.

As WINS only has a single process, then each process has access to each other’s memory. This means that bad pointers may cause corruption of another process’s memory, resulting in bugs which would not occur on a multi-process EPOC implementation. Also, design bugs such as using pointers across processes do not show until code is first run on a multi-process platform.

GUI programs should be built under WINS as .app files in a mapped directory, e.g. \system\apps\program-name\program-name.app. This may be on any mapped Emulator drive.

Such programs must be run by invoking the window server executable, \epoc32\release\wins\variant\epoc.exe. This, in turn, loads a shell that can be used to run the .app.

CONE and Window server programs are a relatively specialised kind of program which use graphics facilities, but do not use the standard GUI.

They should be built as .dlls in ..\epoc32\release\wins\variant\. They can be run by starting the window server executable, and having it start the window server shell.

The window server executable is ..\epoc32\release\wins\variant\epoc.exe.

The window server shell will start up if the mapped file \system\data\wsini.ini either does not exist on any mapped drive, or does not contain a shellcmd line.

The window server shell will only run programs listed in mapped file \epoc32\data\dll_list.txt. This file should contain lines of the form

wsdraw

which refers to wsdraw.dll in the same directory as epoc.exe was started from.

On target machines, .exes are used for command-line programs, and for servers. WINS, however, cannot launch .exes.

Command-line programs are launched by having WINS start-up code built into them.

Servers are launched by building them as DLLs under WINS, but .exes under the ARM environments. This is controlled from a .mmp file by specifying a target type of exedll or epocexe.

The Console APIs required for Text-mode programs are not part of the public API. However they are used in some of the example test code.

Text-mode programs use the text window server — they should be built under WINS as .exe files in \epoc32\release\wins\variant\. They should be executed by running them directly from a Windows command prompt, or under the Microsoft Visual C++ debugger.

WINS is a comprehensive emulator. There is very little difference between programs built to run under WINS, and those built to run on target machines under ARMI. In general, there are no special considerations for building a program under WINS. For interactive development, open the workspace in the Microsoft Visual C++ debugger, and iteratively edit, compile and debug the program.

When the program has been built satisfactorily, it should recompile under ARMI and should function without change on a target machine. Note that the bldmake and abld build framework can also be used to efficiently build WINS and ARMI projects on the command line.

You do need to note a few specific points about WINS development.

See also

Building project files for Microsoft Developer Studio (Visual C++ 6.0)

Servers and other programs which must launch a separate process under ARMI are constructed as .exes under ARMI. Under WINS, this is not possible: servers are therefore constructed as DLLs.

mmp files supports this using statements of the form

targettype exedll
target eusrv.dll

where exedll indicates that the extension .exe will be used under ARMI, but the supplied extension (in this case, .dll) will be used under WINS. You need to conditionally compile the E32Dll() function under WINS only, because E32Dll() is required for DLLs, but not for .exes. This is a minor difference which is very easy to implement and test.

epocexe can also be used as a targettype: unlike exedll programs, these are not expected to export functions to clients, or to be passed command-line parameters.

ARMI implements drivers for real hardware; under WINS, you use Win32 facilities to access or emulate hardware. This means that WINS device-level code must be substantially different from that used by ARMI.

First, you will need substantial conditional compilation. Device drivers will need full testing under both WINS and ARMI. In general, a WINS device driver is best considered as a separate project from a corresponding ARMI device driver.

Usually, in order to implement this kind of code, you will also need to access Win32 libraries. Specify them to makmake using .mmp specifications such as

start wins
win32_library kernel32.lib gdi.lib
end

Under WINS, the following macros are defined by makmake:

__SYMBIAN32__ indicates EPOC code in general __VC32__ indicates the Microsoft Visual C++ compiler __WINS__ indicates the WINS platform __DLL__ if applicable, indicates that a DLL is being built __EXE__ if applicable, indicates that a .exe is being built

in addition to any macros defined by Microsoft Visual C++, and any specified when makmake is run, in the environment variable USERDEFS.

These macros may be used in order to control conditional compilation.

The scheme used to implement UIDs for executables under WINS relies on data in a named data segment. It is only important to include UIDs in WINS executables when generating a polymorphic DLL — such as a device driver, or an standard GUI application.

The build tools automatically generates a stub file, eg ikhello.uid.cpp, which is built by the project and which contains the UID information. This stub file should not be edited, and should be considered as an intermediate file rather than a source file. It has a syntax such as:

#pragma data_seg(“.E32_UID”)
__WINS_UID(0x10000079,0x1000006c,0x10000253)
#pragma data_seg()