Microsoft Corporation September 1997

Introduction

Many Microsoft® Windows® 95 applications can be ported to Microsoft Windows CE with much less effort than would be required to develop them from scratch. The major issues you will need to address when porting to Windows CE are:

Differences between the Microsoft Win32® application programming interface (API) and Windows CE application APIs
Differences between standard the Microsoft Foundation Class Library (MFC) and MFC for Windows CE
Memory limitations and out-of-memory recovery
Energy limitations
Widely varying hardware characteristics and limitations
Differences in testing and debugging

Differences between the Win32 and Windows CE APIs

The Windows CE API differs from the Win32 API in several important respects:

It is smaller. Only a subset of Win32 API is supported, and some of what is supported has a reduced feature set—fewer supported window styles, for example, and more limited support for colors and fonts.
There are Windows CE–specific extensions. Many of these—including the touch screen and notification—support the hardware capabilities of the various devices, but some—the command bar, for example—replace corresponding elements of Win32.
There are limitations on the use of exception handling. While there is support for Win32-structured exception handling, Windows CE does not support C++ exception handling.

When porting existing Win32 applications from the PC platform to Windows CE, the primary issue will usually be the smaller API. Applications will need to accommodate the limitations of the Windows CE API and the capabilities of the target devices.

Differences between Standard MFC and MFC for Windows CE

The Microsoft Foundation Class Library has become an increasingly popular tool for the development of advanced Windows applications. MFC offers a robust and comprehensive set of classes for the development of graphic user interfaces, data manipulation, and system interfaces.

MFC for Windows CE has been designed to closely match the functionality and features of standard MFC, but there are significant differences in the classes available and the features supported in each class. In addition to these differences from standard MFC, there are certain classes in MFC for Windows CE that are unique to the Windows CE platform. For example, an important new feature in Windows CE is the command-bar control.

If your application has been written using standard MFC, you will need to carefully examine the classes, methods, and properties used in your application and verify that they are compatible with MFC for Windows CE.

Memory Limitations

Windows CE devices will, in general, have much less RAM available than a desktop PC. In addition, most will have no disk drive or other mass-storage device. In most cases, successfully porting an application to Windows CE will require reducing its size.

When porting an application to Windows CE, you should focus on the features that are used most frequently. Microsoft Pocket Word and Microsoft Pocket Excel are examples of how to reduce the feature set of an application while still maintaining its essential functionality.

Applications should be written to use as little memory and storage as possible. They must also be able to cooperate with the system in managing memory shortages.

Energy Limitations

Windows CE devices may have very limited energy resources. The Handheld PC (H/PC), for instance, runs on two AA batteries. Programs should be written to minimize energy consumption as much as possible. In order to conserve energy, many Windows CE devices will shut down if they are not used for a period of time. Windows CE applications are expected to resume where they left off following a shut down. If a critical power shortage occurs while an application is running, that application must be able to handle the situation gracefully.

Hardware Characteristics

Windows CE is designed to run on devices that are, in general, smaller and less powerful than desktop PCs. For example:

Screens are typically smaller, have fewer pixels, and may not support color.
CPUs are slower.
User-interface hardware such as keyboards may be less flexible.

On the other hand, some devices may include hardware that is not standard on a PC—the infrared transceiver found on H/PCs, for instance. In any case, do not assume that all Windows CE–based devices are essentially similar to either a desktop PC, or each other. Keep the hardware characteristics of the target device firmly in mind.

When porting an application to more than one class of devices, it will be necessary to find a "lowest common denominator" to ensure that the application will be successful on all its target platforms. Although emulation is an important development tool, applications must ultimately be tested on actual devices to be certain that they perform properly.

Testing and Debugging

Developing applications for Windows CE is very much like developing applications for other Win32 targets, but there are important differences in the testing and debugging methods you will use. If you are developing for a standard Windows CE target (such as the H/PC), then much of your development and testing work can be done using the Windows CE emulation environment provided with your development tools. If, however, you are developing an application for a nonstandard hardware platform (such as a custom-embedded application), then you will need to consider alternate methods for verifying the correctness of your application. The Windows CE API includes interfaces for debugging (such as DebugActiveProcess and DebugEvent) that can be used to create in-system debugging tools. Depending on your target hardware and application, you can also use the Remote API (RAPI) features of Windows CE to assist in debugging.

In any case, you will need to thoroughly test your application on all classes of device that it is expected to operate on. You should not rely on emulation environments to provide adequate testing.

A Systematic Approach to Porting Applications to Windows CE

A systematic approach to porting applications from Windows 95 to Windows CE should produce an application that is nearly, if not completely, ready to run.

The intent of this section is not to provide an exhaustive description of the necessary steps, but rather to highlight the key issues.

Porting to the Windows CE API

If your application is 16-bit Windows–based, the first step is to port it to Win32. While Win32 generally supports 16-bit Windows functions to provide backward compatibility, Windows CE does not.

Next, examine all the API references in your application—including functions, messages, and associated data types—and either modify or replace those that are not compatible with the Windows CE API. Some examples of what to look for:

Some Win32 functions are not supported at all—and no 16-bit Windows functions are supported. Replace these functions with alternative functions, if available, or create a work-around. For example, the MoveTo and LineTo drawing functions are not supported in Windows CE. An alternative is the PolyLine function.
Some Win32 functions have been replaced by Windows CE equivalents. For example, tool and menu bars have been combined into a single Command Bar, which has a new API.
Some Win32 functions are supported, but with limitations. Some may have one or more parameters completely disabled. Others may have parameters with a reduced range of options. For example, while both the CreateWindow and CreateWindowEx functions are supported, Windows CE only supports a subset of the Win32 window styles.
Supported data types may require modification. All necessary Win32 structures are supported, but some members may not be used. Other structures may not accept the full range of options.
Some messages are not supported—including many WM_* and EM_* messages. Some that are supported have been modified. For example, the content of wParam or lParam may be different. Some Windows CE–specific messages have been added—WM_HIBERNATE, for example.

Managing Windows CE Memory

The amount of available memory is device dependent, so be aware of the capabilities of your target platforms. Windows CE makes no distinction between using mass storage (temporary files, for instance) and using RAM.

Reduce the usage of memory and mass storage in your Windows CE application. Consider whether memory-intensive features like bitmapped graphics can be simplified or eliminated. Don't use temporary files unless they are necessary. In some cases, code can be rewritten to reduce memory usage at a cost of somewhat lower speed, which may be an acceptable tradeoff.

If memory resources become tight, Windows CE has a procedure to reduce memory usage and restore available memory to acceptable levels. A key to this procedure is the WM_HIBERNATE message, which is not a standard Win32 message.

Note A well-behaved program must implement a handler for WM_HIBERNATE and cooperate as needed when memory resources become stressed.

Managing Available Power

Many Windows CE devices will be battery operated and have a very limited energy supply. An active (running) CPU consumes significant quantities of energy, so avoid coding practices that use CPU cycles unnecessarily. The PeekMessage function, in particular, should be used with care, as it can keep the CPU running almost continuously.

Windows CE displays warning messages when the batteries start to run low but does not send any warning to applications. For many applications, these messages may be sufficient to ensure that the user takes appropriate action to avoid loss of data.

However, some hardware—modems, for instance—can drain batteries rapidly. If your program is going to place significant demands on the batteries, check the state of the batteries first. If they are too low to complete the procedure, the user can be advised to take appropriate action. Determining the state of the batteries can be accomplished by polling the system.

Porting the Graphics Device Interface

Most PC applications have a graphics device interface (GDI) that is inappropriate for Windows CE, and must be modified before being ported. To keep the footprint of the operating system small, a number of Win32 GDI functions are not supported. In addition, the limitations imposed by hardware on many devices—limited screen size, palette, and aspect ratio, to name a few—will require a somewhat different approach.

Adapting bitmaps and icons

In general, Windows CE devices will have smaller screens and a different aspect ratio than a desktop PC. You may need to modify your application to fit in these smaller constraints; however, don't code static layouts because different target devices can have different screen dimensions and aspect ratios. Instead, use the GetSystemMetrics function to obtain the screen dimensions and use those to define window size.

The available palette can be quite restricted. Some devices support a color screen, although probably with a more restricted palette than a typical PC. Many will have only grayscale graphics—the first generation of H/PCs, for instance, supported only two-bits-per-pixel grayscale LCD displays.

Make sure that bitmaps and icons are in an appropriate format for the target device. LCD screens can be difficult to view in some settings, so keep the contrast as high as possible.

Using Unicode

Windows CE is a Unicode environment—it supports ASCII functionality to allow the exchange of text files, but the native text format is Unicode. Some general guidelines for converting an ASCII application to Unicode are:

Include Tchar.h. It has all the necessary conversions.
Use the Win32 string functions (lstrlen, for instance) rather than those from the C run-time library.
Use TCHAR, LPTSTR, and so on, for declarations. The code can then be easily compiled for either ASCII or Unicode.
Use the TEXT macro for string literals (for example, TEXT("Your Text")).
Remember that a character is no longer one byte in length, and strings end with two zeros rather than one.
When incrementing an array pointer or character count, use sizeof(TCHAR) to ensure that it is valid for either ASCII or Unicode.

Creating and Managing Windows

Creating and managing windows with Windows CE is much the same as it is with Win32. However, you have fewer window-style and management options.

Probably the most noticeable difference is that while windows can be moved, a user cannot resize them—there are no resize handles or buttons available. A window can only have the size specified when it is created. If another application takes the foreground, there will be an icon on the taskbar that can be used to recover the original window. The fact that windows cannot be resized means that some commonly used window styles—WS_OVERLAPPEDWINDOW in particular—are not supported.

When targeting devices with small screens, your application should use full-screen windows. However, don't code static layouts because different devices can have different screen dimensions. Most currently available H/PCs are 240 × 480 pixels and roughly 2.5 × 4 inches. Some have 240 × 640-pixel screens that are also somewhat wider, changing both the pitch and the aspect ratio. Call the GetSystemMetrics function to get the relevant screen dimensions and use those to define window size.

Using Windows CE Dialog Boxes

Windows CE supports both modal and modeless dialog boxes and the predefined controls found in Windows 95. However, not all control styles are supported. Message Boxes are also supported, although with fewer styles than for Windows 95.

Windows CE supports simple implementations of the common dialog boxes, Open and Save As. Their on-screen appearance is similar to Windows 95, but there are fewer controls available.

Porting User Interface Controls

Most of the standard Windows controls and common controls are supported, but there are some limitations. One major difference is that the menu and toolbars are combined in a single command bar that occupies the top of the window and has its own API. Tool tips are only supported for buttons on the command bar.

In general, there is a more limited range of options available.

Managing Windows CE Threads

Windows CE is a multithreaded operating system, but there are some limitations relative to the Windows 95 and Microsoft Windows NT® operating systems. Probably the biggest difference is that semaphores are not supported. If your application uses semaphores, for example, to manage device resources, it will need to be modified to use some other method of coordination between threads. For example, you could modify your application to use critical sections for thread synchronization.

Modifying the User Interface

The user interface may be one of the more difficult issues you will have to deal with. Virtually all PCs have a mouse and a keyboard for input, and a screen for output that is more or less similar on virtually all machines. A program that works on one machine will usually work on all. Windows CE involves a class of devices that not only differ from PCs in many ways, but may also differ significantly from each other.

An H/PC device, for instance, uses a small LCD touch screen instead of a mouse. When the screen is touched with a stylus, a WM_LBUTTONDOWN message is generated in much the same way as with a normal PC. There is no cursor, however, as the device has no way of keeping track of the stylus if it is not in contact with the screen. Because there is, in effect, only one mouse button, there is no WM_RBUTTONDOWN message—the standard alternative is to use the ALT key in combination with a tap.

Other Windows CE devices may be more specialized than the H/PC and depart further from the PC model. The user interface may use speech or handwriting recognition, either as a supplement to or replacement for the conventional mouse-plus-keyboard. The keyboard may consist of only a small number of buttons—sufficient to navigate a menu, for instance. Text to speech may substitute partially or wholly for on-screen display of information.

Visual display may vary widely. The size, aspect ratio, and number of pixels may vary substantially with different devices. Some devices may not support color. Others may, but the available palette may vary.

In short, there are no simple rules that will work for all Windows CE devices. To port a program successfully, know the peculiarities of the target platforms, and make whatever modifications are necessary. While PC-based emulators are valuable development tools, they have their limits. To be certain that the user interface is well designed and functional, it is essential that it be tested on the actual devices it is intended for.

Supporting Windows CE Communications

Windows CE supports four communications APIs:

Windows Sockets (Winsock)
Telephony application programming interface (TAPI)
Remote Access Server (RAS)
Serial Communications

These four communication APIs are subsets of the corresponding Win32 APIs.

Winsock support

The Windows CE network stack supports the Transfer Control Protocol/Internet Protocol (TCP/IP) suite. If your program uses Winsock calls to handle network traffic, it will probably need little modification. The IRDA (Infrared Data Association) specification is also exposed via a Winsock annex. However, there are some limitations on Winsock. In particular, the WSA functions are only partially supported. You will need to carefully examine your use of WSA functions to determine if modifications will be needed.

Client applications can connect to networks running IPX, NetBEUI, or TCP/IP protocols via a subset of the Point-to-Point Protocol (PPP) suite. There is a special host name, "ppp_peer", which serves as a proxy for the IP address of the machine that the device is connected to. Windows CE also supports Serial Line Internet Protocol (SLIP).

TAPI support

The Windows CE operating system implements TAPI version 2.0. TAPI support in Windows CE is focused on outbound data calls, and provides only the basic tools needed for outbound dialing and address translation.

RAS support

RAS is a software-based multiprotocol router used to connect a remote device (the RAS client) to a host PC (the RAS server). RAS applications usually execute on the client device. Windows CE supports many of the standard Win32 RAS functions; however, it supports only one point-to-point connection at a time. The connection can be a direct serial connection or a dial-up modem connection. The RAS phone book contains the information necessary to establish a connection.

Serial Communications support

For serial port communication, Windows CE supports the Win32 serial functions and standard file-system functions. These functions can be used to open, close, and manipulate serial communication ports, as well as read from and write to those ports. Windows CE does not support overlapped communication operation but it does support multiple read/write operations pending on a device.

Minimizing Registry Usage

Use the Windows CE registry carefully to keep memory requirements to a minimum and maximize access speed. Keep registry entries as simple as possible by following these guidelines:

Limit the length of each key name component.
Limit the number of keys needed to get to a value.
Don't use the NULL (default) value name.
Don't use many little values; use a few big ones.
Don't use Windows 95 key-naming conventions only for the sake of consistency. It is often not the most efficient approach.
Keep values as small as possible—don't drop multikilobyte values into the registry.

© 1999 Microsoft Corporation. All rights reserved. Terms of use.

Page