Configuration of Environment Settings in UIQ 3

Symbian OS and UIQ 3 provide support for dealing with the complexity of configuring the development environment. Environment settings are available to configure the emulator for various phone styles, to determine which communication ports to use and to provide connectivity through the PC.

For most application developers these settings are more or less irrelevant; the emulator's default settings are perfectly adequate. But for anyone looking into developing communicating software, there are several settings to be considered in order to configure an SDK environment that is suitable for developing and testing. Even developers of applications that are targeted for UIQ phones with varying phone styles will want to adjust the settings.

This guide explains what these settings are and how they can be configured using the UIQ Environment Configuration Tool (UiqEnv).

The tool for setting common configuration properties for the SDK environment is called UiqEnv. It is included in the SDK. To run the tool, enter "UiqEnv" on the command line before starting the emulator. Configuration changes are only updated during start-up. You cannot change the settings while the emulator is running.

Detailed information regarding arguments and options are provided by the tool. Run UiqEnv without arguments or with the -h flag for this information.

One of the worst headaches for many Symbian OS developers is configuring communications components in a way that meets their needs. One of the most important aspects of this is the configuration of mapping between COM ports in the emulator and COM ports in the host environment. This mapping needs to be done for Internet connectivity, Bluetooth and IrDA.

The main port settings within Symbian OS are for Bluetooth, IrDA and cable. Each one requires port mapping that does not conflict with the others. Otherwise, the system may behave irrationally.

CommsDat, the Symbian database holding information about Internet Access Points, modem bearers etc., can be configured manually by editing the source XML file and running the configuration script, CED. This is, however, a complex method. Therefore, UiqEnv provides a much easier way to set common configurations.

The preferred way to achieve Internet access with the emulator is by piggy-backing on the Ethernet connection of the host system. This has the benefit of not requiring any free COM ports. The only prerequisite is that the WinPCap library is installed. The WinPCap library is available, free to use, at http://winpcap.polito.it. Version 3.1 Beta4 or later is required.

If the Ethernet solution is not appropriate for your environment, there are two alternatives. One involves using a connection through the host system with an NT RAS connection through a loop-back NULL modem cable; see Setting Internet Access through NT RAS below. The other is using dial-up or GPRS access by connecting the emulator, through a cable from a COM port, to a mobile phone. For both of these solutions, the port used to connect the cable may differ between host systems and needs to be set; see Setting Ports below.

For developers interested in Bluetooth connectivity, attaching a Bluetooth dongle to the host system and using it in the emulator is much easier than building target binaries and testing on hardware during development.

Connecting an Infrared pod to the host system and using it through the emulator is another way of avoiding time consuming testing on hardware during development.

In both cases, the ports must be set properly. See Setting Ports below.

UIQ 3 is a platform capable of supporting several different phone styles with just one codeline. For example, one UIQ phone might be configured for one-handed use without a touch screen, using only keys for input, and a screen in portrait layout. Another UIQ phone might make use of a touch screen in landscape mode. How to develop an application capable of displaying output and handling input for these different phone styles is beyond the scope of this guide. It does, however, cover configuring the settings for the emulator.

In UIQ 3 a component called UiConfigServer handles the UI configurations and notifies applications of changes. This server is also responsible for being aware of the default phone styles configurations. The default UI style configuration cannot be changed by the user or by an application. However, anyone who wants to develop an application capable of running on UIQ phones, using different phone styles, needs to be able to detect the UI style in use.

For development purposes, UiqEnv allows application developers to change the UI Style Configuration in the emulator in order to develop and test applications on phones with varying phone styles. The setting is an integer bit mask with four positions, combining parameter values. See epoc32\include\qikon.hrh for more details.

Phone Style Parameters and Values

The parameter values are combined using bit-wise OR. This results in a hexadecimal number. Converting the hexadecimal number to a decimal integer gives us the code for a specific UI style configuration.

For example, the default UI style configuration is called One Handed Portrait. It has the parameters Screen Mode Portrait, Touch Screen No, UI Style Softkey and Orientation Normal. Replace the parameters with the values and perform the OR-operation: 0x0001 | 0x0040 | 0x0200 | 0x4000 = 0x4241. Converting 0x4241 to decimal form gives us 16961 which is then the code for One Handed Portrait configuration.

This can be set by running UiqEnv, the UIQ Environment Configuration Tool.

UiqEnv –ui 16961

It is also possible to refer to each of the two predefined configurations by name: "softkey" for one-handed, without a touch screen and using softkeys or "pen" for pure touch-screen based input in portrait mode.

UiqEnv –ui softkey
UiqEnv –ui pen
            

UiqEnv has a range of options available for configuring connectivity. This section describes some common configurations.

UiqEnv supports setting each of the three COM ports, individually or all at once, while ensuring that they do not conflict with each other.

Run UiqEnv –ports to print the current port configuration.

All three COM ports can be set at once, for example, UiqEnv –bt 1 –ir 2 –cable 3 sets the COM port used for Bluetooth to 1, IrDA to 2 and cable to 3.

Alternatively, just one COM port can be set, for example, UiqEnv –cable 1 sets the COM port for cable connections to 1 and allocates arbitrary port numbers for IrDA and Bluetooth that do not conflict with COM 1.

IMPORTANT: Setting the cable port to a port that is not available will cause the system to crash.

UiqEnv supports two modes of Ethernet access, with or without a DHCP server. The following properties are relevant.

• MAC address

• NIF ID (Network Interface ID)

• IP Address

• Default Gateway address

• DNS Server address

• Subnet Mask

The -eth flag tells UiqEnv to configure CommsDat to use Ethernet access. The properties above can be given as arguments or they can be omitted. If they are omitted, the tool will acquire these settings from the host system.

Using the values from the host system is in most cases perfectly acceptable. However, on some networks, the routing policies may be such that the MAC address may need to be slightly modified in order to avoid routing conflicts. This can be achieved by either supplying a new MAC address through the -mac parameter or by giving UiqEnv the -mod_mac flag. Using the -mod_mac flag allows UiqEnv to create an appropriate MAC address.

If a DHCP server is used, the -dhcp flag is given. In that case, only the MAC and NIF properties are relevant.

With or without a DHCP server, UiqEnv will create an Internet account on the emulator for the connection.

The -proxy flag can be used to specify a proxy server and port when necessary. This flag requires the IP-address of the proxy server and the port number separated by a ":" as a parameter.

The -clear flag clears all Ethernet and proxy settings. This even removes some settings made when installing the SDK so it should be used with caution. To return to the same state as when the SDK was newly installed use the uiqenv command with the -eth flag.

The conventional way of accessing the Internet through the emulator is by using an NT RAS service on the host system. Configuring the NT RAS service is beyond the scope of this guide, but it requires a serial connection in a loop-back configuration, thus requiring two available COM ports.

For example, run UiqEnv –ntras –cable 2 to configure CommsDat for use of NT RAS through COM 2. This means that the incoming connection port on the host needs its own port, for example COM 1.

UiqEnv will create an Internet account on the emulator for the connection.

The important thing when using a mobile phone as a modem is the COM port for connecting the serial cable. UiqEnv supports setting this port. See Setting Ports above.

However, UiqEnv will not create an Internet account on the emulator for the connection. You need to create an Internet Account for either dial-up or GPRS in the Control Panel of the emulator, with the relevant account details, such as username and password, for the account that is being used by the mobile phone.

The connection to the phone can be made with Bluetooth or IrDA instead of cable. The port must then be set for Bluetooth or IrDA instead of for cable.