UIQ 3 Developer Library Configuration of environment settings in UIQ 3 Page 1 of 9

Configuration of Environment Settings in UIQ 3

Configuration of Environment Settings in UIQ 3 1

1 Introduction 2
1.1 UiqEnv, the UIQ Environment Configuration Tool 2
2 Connectivity 3
2.1 Internet Connectivity - Ethernet and Cable 3
2.2 Bluetooth and IrDA Connectivity 3
3 UI Style Configuration 4
4 Settings 6
4.1 Setting Ports 6
4.2 Setting Internet Access through Ethernet 6
4.3 Setting Internet Access through NT RAS 7
4.4 Setting Internet Access through a Cable-Connected Mobile Phone 7
Legal notice 8
Document History 8
Developer resources 9

© UIQ Technology AB 2007. All rights reserved.

UIQ 3 Developer Library Configuration of environment settings in UIQ 3 Page 2 of 9

1 Introduction
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).

1.1 UiqEnv, the UIQ Environment Configuration Tool

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.

© UIQ Technology AB 2007. All rights reserved.

UIQ 3 Developer Library Configuration of environment settings in UIQ 3 Page 3 of 9

2 Connectivity
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.

2.1 Internet Connectivity - Ethernet and Cable

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://www.winpcap.org/. 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 4.3 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 4.1 Setting Ports, below.

2.2 Bluetooth and IrDA Connectivity

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 4.1 Setting Ports, below.

© UIQ Technology AB 2007. All rights reserved.

UIQ 3 Developer Library Configuration of environment settings in UIQ 3 Page 4 of 9

3 UI Style Configuration
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

Parameter Value

Screen Mode Portrait 0x0001

Screen Mode Landscape 0x0002

Touch Screen No 0x0040

Touch Screen Yes 0x0080

UI Style Menu 0x0100

UI Style Softkey 0x0200

Orientation Normal 0x4000

Orientation Inverted 0x8000

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.

© UIQ Technology AB 2007. All rights reserved.

UIQ 3 Developer Library Configuration of environment settings in UIQ 3 Page 5 of 9

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

© UIQ Technology AB 2007. All rights reserved.

UIQ 3 Developer Library Configuration of environment settings in UIQ 3 Page 6 of 9

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

4.1 Setting Ports

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.

4.2 Setting Internet Access through Ethernet

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.

© UIQ Technology AB 2007. All rights reserved.

UIQ 3 Developer Library Configuration of environment settings in UIQ 3 Page 7 of 9

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.

4.3 Setting Internet Access through NT RAS

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.

4.4 Setting Internet Access through a Cable-Connected Mobile

Phone
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 4.1 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.

© UIQ Technology AB 2007. All rights reserved.

UIQ 3 Developer Library Configuration of environment settings in UIQ 3 Page 8 of 9

Legal notice
© 2007 UIQ Technology AB. all rights reserved. All product and company names mentioned
herein may be trademarks or trade names of their respective owners.

UIQ Technology does not make any representations about the suitability of the content,
material or information contained in this document (“Content”) for any purpose. All Content
is provided on an “as is” basis without warranty of any kind. UIQ Technology hereby
disclaims all warranties and conditions with regard to the Content, including all implied
warranties and conditions of satisfactory quality, fitness for a particular purpose, title and
non-infringement. While we attempt to ensure that the Content is accurate, we cannot
guarantee that it will always be fault-free. The Content could include technical inaccuracies
or typographical errors. We endeavor to correct errors and omissions as quickly as
practicable. We do not accept liability for any such errors and omissions. Changes are
regularly made to the Content. UIQ Technology may make improvements and/or changes to
the Services and/or the Content at any time without notice. Other than in accordance with
these terms and conditions or with the prior written consent of UIQ Technology, you may not
modify, copy, distribute, transmit, reverse engineer, display, perform, reproduce, publish,
license, create derivative works from, transfer, or sell any Content.

Full disclaimer: http://developer.uiq.com/disclaimer.html

SDK Terms and conditions of use

Document History
UIQ 3.1 SDK, June 2007

© UIQ Technology AB 2007. All rights reserved.

UIQ 3 Developer Library Configuration of environment settings in UIQ 3 Page 9 of 9

Developer resources
The UIQ Developer Portal has many resources invaluable to developers creating applications,
content and services for all UIQ 3 mobile phones. Free Community membership registration
is necessary for some content and to post messages in the developer forums.

Documentation and code: In this section, you will find all kinds of documentation, ranging
from reference documentation to more tutorial- and guide-style documentation to tips and
code snippets. Learn with the whitepapers and find tips in the knowledgebase.
http://developer.uiq.com/kb.html

Discussion forum: This section is where the community hangs out and where you can get
help or help others to benefit from your experience. Always give as much detail as possible so
that others have all the information needed to give you a helpful reply.
http://developer.uiq.com/forum.html

News and events: Here you can find here the latest news regarding the UIQ developer
community and the list of upcoming and past events.
http://developer.uiq.com/news.html

SDK and tools: The place to download the UIQ Software Development Kits (SDK) and other
tools necessary to develop for UIQ 3.
http://developer.uiq.com/devtools.html

Developer Program: This section provides further information on fee-based membership

programs such as the Premium membership.
http://developer.uiq.com/program.html

Support: For registered members to purchase professional support tickets.

http://developer.uiq.com/support.html

Join the UIQ developer community at http://developer.uiq.com.

© UIQ Technology AB 2007. All rights reserved.