EPOC Emulator

The EPOC Emulator is a Windows hosted implementation of EPOC, including full emulation of an EPOC device. It is the principal development and debugging platform for creators of new EPOC applications, supporting development in C++, Java, and Symbian's BASIC-like OPL language.

As well as forming an essential component of all EPOC SDKs, it is freely available in standalone form from Symbian, providing a showcase for potential EPOC developers and users.

Release 007
Copyright (c) 1997-1999 Symbian Ltd. All rights reserved.


Documentation Conventions


Documentation conventions

Contents

  • Overview
  • Feature level
  • Document level
  • Styles

Overview

This topic provides a quick introduction to the conventions used in this documentation.

Feature level

The icon [image] indicates that the feature was introduced in EPOC Release 5.

Document level

A document level icon at the head of a topic tells you when that topic was last revised. The levels are as follows.

ER5 Document level

The icon [image] indicates that the topic refers to releases up to and including EPOC Release 5 — which is the EPOC Release current with this documentation.

ER3 Document level

The icon [image] indicates that the topic refers to releases only up to and including EPOC Release 3. It is possible that behaviour described in this document has been changed in a later EPOC Release.

Styles

Style | Type
File | Open | Application text and menus
aVariable, Push() | Code. Note that where type names and constants are mentioned, they are hyperlinked to their detailed discussion in the reference documentation.
note this | Emphasised text containing unusual or surprising information
euhello | Example project. This is hyperlinked to the reference page describing the example.
e32std.h | Filename
toolband | Hyperlink to definition in the glossary
dir | Input text to enter
ALT+A | Key names
WINS, ARM, M*CORE | Text only applies to the indicated platform
NUMED | Resource name, resource struct, or resource struct member
syntax | Syntax element in syntax diagrams and descriptions
Warning | Warning of an important issue
EPOC SDK Home Previous Up


Using the EPOC Emulator

  • About the EPOC Emulator
  • Starting the Emulator and applications
  • Using the keyboard, mouse, screen, and sound
  • Files and locations
  • Dial-up networking
  • Debug facilities


About the EPOC Emulator

  • Emulator highlights
  • New features in EPOC Release 5

Overview

The EPOC Emulator provides an implementation of EPOC which runs under Windows on a PC to provide a full EPOC target environment for developers. This implementation of EPOC is known as WINS — the single process Windows platform.

As well as implementing EPOC, the Emulator provides a generic emulation of an EPOC Release 5 device, complete with customisable screen sizes including large (800x600), VGA (640x480), and half-VGA (640x240) in colour or greyscale. By providing developers with a Windows hosted target and a powerful emulation of real devices, the Emulator enables most EPOC development to be substantially PC based. Only the final development stages focus on the target hardware. Of course, for low level programming where target hardware must be directly accessed, such as physical device driver programming, the Emulator is not a suitable development platform.

The Emulator is an essential component of all EPOC SDKs and supports development in a variety of languages, including C++, Java, and Symbian’s BASIC-like OPL language.

This documentation provides the information developers need to use and configure the Emulator. For language specific information about EPOC development using the Emulator, see the SDK for your language of choice.

Note that this documentation only discusses EPOC Release 5 features that are specific to the Emulator. General information, for example about using the standard application set, is not provided.

Emulator highlights

Among its highlights the Emulator includes many small touches which enhance its usability:

  • function key mappings to emulate hardware effects not available on the PC, such as low power
  • special debug keys for EIKON GUI apps, see Debug facilities
  • flexible reconfiguration of the mapping of the EPOC file system onto the PC, see Virtual drives

Other features which contribute to the completeness of the Emulator as a development target include:

  • comprehensive configurability from initialisation scripts, for example to specify screen size and greyscale/colour depth, see About Emulator configuration
  • full integration with the Windows run time enviroment providing support for comms, internet, and IrDA through the host PC, see Dial-up networking

New features in EPOC Release 5

The EPOC Release 5 Emulator introduces some significant new features:

  • full colour support, see Colour
  • extra configuration settings available for the location of virtual drives and pointing device, see Drive emulation by configuration file setting [image] , and Pointer type
  • ability to run from any location: see Alternative Emulator location
  • improved debugging support: when a thread is panicked, the debugger provides comprehensive information about the panic
  • support for international PC keyboard variants
  • any application can now be run from the \system\apps directory of an emulated c:, d:, or other non-z: drive. This corrects an error that meant, previously, some applications could only be run from z:\system\apps.
  • an ER3 restriction that required the correct variant of the console DLL econs.dll to be manually selected has been removed
  • the emulator executable is renamed from wsexe.exe to epoc.exe
  • the configuration file is renamed from system.ini to epoc.ini
EPOC SDK Home Previous Next Up


Starting the Emulator and applications

  • Basics
  • Language-specific development

Overview

This topic describes how to start and stop the Emulator, and run applications. Language-specific development notes extra issues of which developers in various programming languages should be aware.

Basics

EIKON shell and applications

EIKON is the standard GUI framework for EPOC. It has a shell that allows users to start and stop applications, manage files, configure the machine, and so on. It is the only way by which EIKON applications can be started.

The EIKON shell is started by running epoc.exe. The possible locations of this file are described in Files and locations [image] . A number of options can be passed to epoc.exe on the command line to modify the Emulator behaviour. These are discussed in Command line options.

Text console applications

Text console applications perform their input and output through a simple console window, rather than through a graphics shell. They are built as a simple .exe files. The necessary code to create an Emulator console window is built into such applications. You can therefore start them by simply running the exe from Windows.

Closing the Emulator

You can quit the Emulator by closing the Emulator window in the normal Windows ways or, in debug builds of the Emulator, by pressing ctrl+alt+shift+E.

When the Emulator simulates a power-off, it minimises the EPOC Emulator window. Restoring the application simulates an EPOC power-on.

Language-specific development

Developers for different programming languages should note that there may be extra options for how applications are launched. This section contains a brief discussion of such language-specific issues.

OPL

Translated OPL programs (opo files) are run from the EIKON shell. With a few extra steps, OPL programs may also run from the Extras bar. For more details, see the OPL SDK.

Translated OPL programs are machine-independent, so they can be copied between target and Emulator without retranslation. You cannot, however, copy and run programs that use OPXs, as these are written in C++.

Java

There are a number of ways that Java applications on the Emulator can be launched, including from the Windows command-line and from the EIKON shell. For more details, see the Java SDK.

Java programs are also machine-independent, and so can be copied between target and Emulator.

C++

C++ developers face the most complex position, as operating system concepts such as processes and threads are directly exposed to the programmer. The Emulator is a single-process environment, unlike the target environments, which are multi-process. For many EIKON applications, this difference is transparent, as each process is emulated by a Windows thread. There are, however, differences regarding some executables, such as console applications and servers. For more details of these, see the C++ SDK.


Using the keyboard, mouse, screen, and sound

  • Using the PC keyboard
  • Other special hardware features
  • Using the screen and mouse
  • Using sound

Overview

The Emulator allows users to use the PC’s keyboard, mouse, screen, and sound facilities as if they were the real input and output devices of a target machine. This section describes these facilities.

Using the PC keyboard

The keyboard on your PC is similar to, but not the same as, that used on keyboard-equipped EPOC devices. The following table shows some special extra key assignments implemented by the Emulator:

PC key | Device function
Shift | shift on device keyboard
Ctrl | ctrl on device keyboard
Alt | fn on device keyboard
F1 | menu key: press to obtain the menu from an EPOC application
Alt+F2 | help key: press this to obtain general help on EPOC applications

SHIFT, CTRL and Fn are the EPOC modifier keys. Because target machines will almost always have fewer keys than a PC keyboard, EPOC programs should not rely on combinations such as Fn+PgUp, since PgUp may itself be implemented using Fn+Up.

The Menu key is not a modifier.

Note that the Windows locale keyboard setting will be translated by the Emulator into the equivalent EPOC locale.

Other special hardware features

Special features typical of EPOC devices are also available when developing using the EPOC Emulator, through special key assignments.

Removable media support is simulated by two files in the PC’s temp directory, each representing one PC-Card device. Pressing F5 simulates opening the door, and pressing F4 while the door is open switches between the two simulated devices. When the Emulator is started, each device is equivalent to an empty, unformatted, volume. An F32 client under WINS may access the removable media using the EPOC y: drive.

Additionally, the Emulator is able to mimic the three external dictating machine buttons found on the underside of Psion Series 5 devices using special key assignments.

F6 | Play button
F7 | Rewind button
F8 | Record button
F9 | Power off: this minimises the EPOC Emulator window; you can power-on again by restoring the window
F10 | Emergency shutdown: this occurs on target machines when battery voltages fall below a certain level — the machine hasn't enough power to function normally, so it falls into a state in which data on the machine is preserved while there is still power in the main and backup batteries but no user operations are allowed
F11 | Case close toggle: adds the text "CASE CLOSED" to the Emulator window's title bar, and the keyboard and screen become inactive. Press the key again to simulate the case being reopened.

Automatic power-off — for example after a set time — is also simulated. The Emulator application minimises itself; restoring the application causes an EPOC power-on to be simulated.

Using the screen and mouse

The Emulator window shows the screen on an EPOC device, with a sidebar to the left-hand-side, and a taskbar below.

EPOC devices often have touch-sensitive screens. To simulate a tap on the EPOC screen, use the PC mouse. Only the left button is supported.

The touch-sensitive area is extended beyond the LCD area of the screen, to include a sidebar and a taskbar. Use the sidebar to invoke the menu, edit, infrared or zooming functions; use the taskbar to launch or switch between applications:

  • the System icon brings you to the permanently-running System shell, which allows you to navigate around EPOC’s folders and files, and to launch a file by pressing enter, or tapping, on a selected file; also, the System application includes a control panel which can be used to inspect and change various system settings
  • the Word, Sheet, Data, Agenda, Time, Calc and Sketch icons allow you to either launch the corresponding application if it is not already running, or switch to the application if it is already open but you are in a different application, or to switch between instances of the application if multiple instances are open
  • the Extras icon causes other application icons to slide up onto the screen, where they can be selected as if they were part of the permanent, off-screen, taskbar
  • press Ctrl while tapping on System, to see a list of currently-running programs

Using sound

The Emulator can drive the PC’s sound facilities to emulate sound functionality on a target machine. The PC setup should be as follows:

  • a sound card supporting 16-bit PCM with the appropriate driver installed
  • the Microsoft CCITT G.711 Audio CODEC installed in the Audio Compression Codecs section of the Devices page on the Multimedia Control Panel applet


Files and locations

  • Emulator in C++ SDK
  • Alternative Emulator location
  • Location of executable programs
  • Application files

Overview

The Emulator maps the EPOC file system onto the PC’s file system. This drive mapping is performed at run-time. It enables applications to use EPOC file system drives without interfering with PC’s drives in unpredictable ways. EPOC always requires at least two drives: z:, which in target machines maps to the ROM, and c:, a RAM drive.

To allow for the differing requirements of different products containing the Emulator, the default locations for the virtual drives vary depending on where the Emulator itself is installed. This section describes the different cases.

You can also add further virtual drives, and reconfigure the standard drives to map to alternative locations. This is described in Virtual drives [image] .

Emulator in C++ SDK

When the Emulator is used with the C++ SDK, it must be located in the following directories:

  • release build: \epoc32\release\wins\rel\
  • debug build: \epoc32\release\wins\deb\

When this is the case, the EPOC drives z: and c: are mapped by default to sub-directories of the \epoc32\ tree, as follows:

c: | \epoc32\wins\c\
z: | \epoc32\release\wins\build\z\

Therefore, an EIKON application program such as z:\system\apps\ikhello\ikhello.app is mapped by the narrow debug build to \epoc32\release\wins\deb\z\system\apps\ikhello\ikhello.app.

Configuration files for the Emulator are located in \epoc32\data\.

Alternative Emulator location

In some products, the Emulator can be run in another location than \epoc32\release\wins\build\. In this case, the Emulator looks by default for the following sub-directories below its own location:

Name | Description
c | virtual c: drive
z | virtual z: drive
data | Emulator configuration files

Location of executable programs

An exception is made to the standard drive name mapping for non-EIKON executables (exe and dll files):

  • exe files can be anywhere on the PC file system: for example, you could even run an exe from a shared drive on another user’s PC
  • dll files required by other executables are usually build to the parent directory of the virtual z: drive (e.g. \epoc32\release\wins\deb\ if z: is \epoc32\release\wins\deb\z\)

The usual approach is to build both exe and dll files to the z: parent directory.

Note that EIKON application programs, however, must be in their standard locations in the z:\system\apps\ directory tree, in order to appear on the Extras bar.

This usual configuration is determined by the way that the Emulator locates a library file that is to be loaded. In detail, this is as follows:

  • if the filename includes a drive, the filename is mapped using the appropriate virtual drive mapping
  • if the filename is specified without a drive letter, then the virtual z: parent directory is searched
  • if the library is not found, an attempt is made to find the library in the same way as on a target machine: i.e. virtual drives y: to a:, then z:\system\libs\, are searched.

Application files

Application data files can be copied from an EPOC machine, using EPOC Connect, onto an Emulator virtual drive, and opened from within the Emulator.


Dial-up networking

  • Using Email and Web
  • Dial-up with a mobile phone

Overview

Among the standard applications provided with the EPOC Emulator are the Email and Web applications. These can be used from a PC which provides the necessary peripheral devices. Increasingly, developers will want to ensure that their applications are internet and comms aware.

Using Email and Web

On a real EPOC device, the EPOC Email and Web applications use dial-up networking to an Internet Service Provider (ISP). General ISP settings are stored in the control panel; the Email program controls some specific e-mail settings, with specific browser preferences being set up in the Web program.

To use the Email and Web programs on the EPOC Emulator, you need

  • a PC with a modem
  • an ISP account
  • SMTP/POP3 e-mail accounts

The EPOC Emulator’s networking facilities are not designed to work with PC-based LAN networking. Your PC must have a modem and use dial-up networking.

You can use the same ISP as you use for your PC-based Internet access. But you must enter all your ISP settings again, in the EPOC control panel: the Emulator cannot share settings from your PC’s control panel. Additionally, your incoming and outgoing mailbox details must also be set in the EPOC Email application in order to receive and send Internet mail.

EPOC’s serial devices are referred to as COMM::0 and COMM::1. COMM::0 maps to the PC’s COM1 port, while COMM::1 maps to COM2.

Dial-up with a mobile phone

Dial-up through a data-enabled mobile phone with an infra-red port is supported by choosing a modem type of Infra-red mobile phone. Setting the Connect via option to Infrared causes the emulator to drive an IrDA COM-port serial adapter on the PC. The recommended adapter is the Extended Systems, Inc. Jeteye ESI-9680.


Debug facilities

  • Debugging keys

Overview

The Emulator is designed to be the primary development and debugging tool for EPOC, alongside any language specific tools provided by development environments.

In debug builds of EPOC, the EIKON GUI provides special key combinations for resource checking and redraw testing, which can help to trap memory leaks early in the development cycle. All EIKON debug keys are accessed using a ctrl+alt+shift prefix. The Emulator provides these debug key combinations in its debug build.

Debugging keys

All EIKON applications may be exited using ctrl+E. Additionally the Window Server provides ctrl+alt+shift+K to kill the application with current keyboard focus, and ctrl+alt+shift+X to bring down the Emulator.

Drawing:

M | brings up Move me dialog, which can be moved around with the pointer, to test whether applications handle partial redraw properly
R | redraw whole screen, to test whether applications handle complete redraw properly
F | enable window server auto-flush for all programs using the current control environment
G | disable window server auto-flush for all programs using the current control environment

Miscellaneous features:

V | turn on or off verbose information messages
Z | send keys A through J in fast sequence to the application, to test its ability to handle fast repeated keys

Resource allocation:

A | show number of heap cells allocated on user heap by the current program
B | show number of file server resources in use by the current program
C | show number of window server resources in use by the current program
P | show dialog for the heap failure tool: see below for details.
Q | turn off heap failure mode

The heap failure tool artificially generates resource allocation failures. It is used by developers to test that an application copes properly with such failures. The dialog options are as follows:

  • App heap failure Type: generates failures for resource allocation requests from applications. Random means that requests fail at a random rate. Deterministic means that requests fail at the rate specified in the Rate box.
  • Wserv heap failure Type: generates failures for resource allocation requests from the EPOC window server. The options are as for App heap failure.
  • File failure tool: selecting this option generates failures for file access attempts.
EPOC SDK Home Previous Up


Configuring the Emulator

  • About Emulator configuration
  • Virtual drives
  • Emulator appearance
  • Pointer type
  • Memory capacity


About Emulator configuration

  • Emulator configuration file
  • Command line options
  • Selecting an Emulator configuration

Overview

The main areas where configuration can take place are:

  • appearance
  • virtual drives

Most configuration settings are held in an Emulator configuration file. Some additional choices can be made through specifying command-line options when launching the Emulator.

Emulator configuration file

The Emulator configuration settings are held in a configuration file in the \epoc32\data\ directory. A configuration file can contain commands to define:

  • appearance: see Emulator appearance
  • virtual drives: see Virtual drives
  • pointer device type: see Pointer type
  • memory capacity: see Memory capacity

The default configuration file is called epoc.ini. To change these defaults, you can:

  • edit epoc.ini
  • create a new configuration file, and tell the Emulator to read its settings from that. This is done through a command line option.

Any configuration file should have associated with it a bitmap file that is used as the fascia (the area with icons that surrounds the emulated window). The file must have the same name as configuration file being used — i.e. the default fascia is epoc.bmp. Licensee users can edit the fascia bitmap to present a different machine appearance.

Command line options

Command line options allow you to specify:

  • a configuration file to use: see Selecting an Emulator configuration
  • the path of the emulated c: drive: see Drive emulation by command-line option

The form of command line options is:

<program> <option-list> --
program | the program you wish to invoke: epoc for a graphics shell, or the executable name for a text program
option-list | one or more options in the following form: -<option><argument>
option | a single letter specifying the option type
argument | option type-specific argument

Note that the option list must be terminated with two hyphens.

Options and arguments are case sensitive.

Selecting an Emulator configuration

The Emulator is supplied with various configuration files and fascia bitmaps that set the appearance of the Emulator to the standard screen sizes supported by EPOC Release 5:

  • epoc.ini (the default) — generic half-VGA device 640 x 240 pixels, for example the format used by the Ericsson Mobile Companion MC 218 as well as the Psion Series 5
  • vga.ini — VGA device 640 x 480 pixels
  • large.ini — SVGA size device 800 x 600 pixels

You may select a configuration with the M command line option, giving the name of a configuration file as the option argument. For example, the following command runs the Emulator in a large screen mode (note the required trailing minus symbols):

    epoc -Mlarge –-


Virtual drives

  • Drive emulation by configuration file setting
  • Drive emulation by command-line option
  • Drive emulation by environment variables

Overview

As described in Files and locations [image] , the EPOC drives z: and c: are mapped by the Emulator onto some default locations in the PC file system. This topic describes how you can change these default locations, and how you can add further virtual drives — for example, to simulate a CF card acting as a removable drive.

There are a number of ways of performing these tasks. The recommended method is to use the configuration file. If required, you can also override the location of the emulated c: drive using the command-line. Finally, an environment variable method was provided for ER3, and is now deprecated.

Note that any mapping for the z: drive must specify a directory named z.

Drive emulation by configuration file setting

The location of virtual drives can be specified by entries in the Emulator configuration file (usually epoc.ini). You can override the default locations of z: and c: drives, or specify additional drives.

An entry should have the form:

_EPOC_DRIVE_<drive-letter> <location>

For example, you could specify an additional d: virtual drive using the setting:

    _EPOC_DRIVE_D A:\

which would allow the Emulator to treat your PC’s diskette drive as its own removable drive, which is usually mapped to d: on target machines.

Drive emulation by command-line option

Command line options can be used to specify the location of the emulated c: drive. A location set in this way overrides the default settings and any _EPOC_DRIVE_C setting in the environment or in the configuration file.

Command | Description
-C<emulated C drive> | The argument specifies the path of the directory that should be used for the emulated c: drive.
-T | Specifies that the system temporary path should be used as the emulated c: drive.

For example,

    epoc -Cd:\test\ --

maps the virtual c: drive to the path to d:\test\.

Drive emulation by environment variables

In addition to the drive emulation methods previously described, you can also specify virtual drives using environment variables. This is for backward compatibility with ER3: you should now use the epoc.ini method.

The environment variable setting has the form:

_EPOC_DRIVE_<drive-letter>

For example,

    set _EPOC_DRIVE_P=c:\test\

sets a virtual drive p:, with the real location c:\test\.


Emulator appearance

  • Emulator configuration file
  • Colour

Overview

The appearance of the Emulator may be customised by editing two configuration files. The main Emulator configuration file controls screen size, position, and LEDs. The Emulator can also be configured to be in colour or black and white through another configuration file.

Emulator configuration file

The description of the settings is divided into the following areas:

  • screen size and position
  • LEDs

Any setting not specified in a configuration file is given the value listed in the Default column.

For example, the generic configuration file epoc.ini, has the settings:

    ScreenOffsetX 99
    ScreenOffsetY 40

which sets the position of the Emulator screen to non-default values.

Screen size and position
Item | Description | Default
ScreenHeight | Height of the screen in pixels. | 240
ScreenWidth | Width of the screen in pixels. | 640
PhysicalScreenHeight | Height of the screen in twips. | 2858
PhysicalScreenWidth | Width of the screen in twips. | 7620
ScreenOffsetX | Horizontal offset of the Emulator screen from the top-left of the window in pixels | 90
ScreenOffsetY | Vertical offset of the Emulator screen from the top-left of the window in pixels | 51

The twips settings allow the GDI’s twips-to-pixels mapping functions to be changed according the size of the physical screen on the emulated model. The default values correspond to 0.21mm pixel size or 121 pixels per inch.

LEDs

The Emulator simulates two hardware LEDs. The following settings determine the appearance of these LEDs.

Item | Description | Default
LedArrangeVertically | Arrange LEDs vertically. This is the default. |
LedArrangeHorizontally | Arrange LEDs horizontally. |
LedGap | Gap between LEDs in pixels. | 5
LedOffsetX | Horizontal offset of LEDs from the top-left corner of the window in pixels. | 36
LedOffsetY | Vertical offset of LEDs from the top-left corner of the window in pixels. | 45
LedSize | Diameter of LEDs in pixels. | 14

Colour

A batch file instcol.bat, installed in \epoc32\tools\, can be used to switch between colour and greyscale versions of the Emulator.

For colour, type:

INSTCOL CL

For greyscale, type:

INSTCOL BW

Details

instcol.bat installs the appropriate versions of .aif and .mbm files, and of wsini.ini.

  • .aif and .mbm files are used to store the icons which represent an application when it is embedded or appears in the System screen or on the Extras bar. The Emulator is supplied with two sets of .aif and .mbm files. Greyscale and colour .aif files are supplied as *.abw and *.acl respectively and .mbm files are supplied as *.mbw and *.mcl.
  • the color display mode settings for the Emulator are set in the wsini.ini configuration file for the window server — the EPOC component that manages the screen, keyboard and pointer. For details of this file, see the "Window server configuration" topic in the EPOC C++ SDK System Documentation. Colour and greyscale versions of wsini.ini files are supplied.


Pointer type

The PointerType [image] setting in the emulator configuration file sets the type of pointer device that is available on the target machine.

Possible values are:

  • PEN
  • MOUSE
  • NONE

The setting determines the events that the window server makes available to applications.

PEN simulates pen input: events only occur when the when the pen is touching the digitiser—in the emulator, when the left mouse button is depressed. With MOUSE, an application also gets Move events: that is, an application can detect a mouse moving even while the button is not pressed. NONE is not currently supported.

The standard shell and applications do not respond to Move events, so the setting value does not alter their behaviour.


Memory capacity

The MegabytesOfFreeMemory setting in the emulator configuration file sets the maximum total heap size in megabytes, in order to emulate target machines with different memory capacities. If this parameter is not specified, the amount of free memory defaults to 64MB.

If you wish to limit the heap, it is conventional to allow one megabyte for EPOC system use: for example, specify 7 to simulate a 8MB machine.

EPOC SDK Home Previous Up


  • Documentation Conventions
    • Documentation conventions
  • Using the Emulator
    • About the EPOC Emulator
    • Starting the Emulator and applications
    • Using the keyboard, mouse, screen, and sound
    • Files and locations
    • Dial-up networking
    • Debug facilities
  • Configuring the Emulator
    • About Emulator configuration
    • Virtual drives
    • Emulator appearance
    • Pointer type
    • Memory capacity