May 1999
© Microsoft Corporation, 1999. All rights reserved.
Welcome to the Microsoft® Windows® CE Platform Software Development Kit (SDK), Auto PC Edition 1.0. This kit contains the essential tools that you need to develop an application for an Auto PC running the Microsoft® Windows® CE for the Auto PC operating system.
Enjoy using this product to develop great new applications for Windows CE for the Auto PC!
The Windows CE Platform SDK, Auto PC Edition 1.0 provides tools that help you build applications for an Auto PC. This release supports emulation of an Auto PC on your desktop computer. This SDK does not include the cross-compilers needed to develop binary files that run on an Auto PC. The Microsoft® Windows® CE Toolkit for Visual C++® 6.0 includes these compilers. Alternatively, you can use any C or C++ development environment that supports Windows CE.
To ensure that emulation functions properly, be sure that your desktop computer runs the Microsoft® Windows NT® 4.0 operating system. Emulation is not supported on the Microsoft® Windows® 95 or Microsoft® Windows® 98 operating systems. Install your development tools in the following order:
The Windows CE Platform SDK, Auto PC Edition 1.0 has hardware requirements greater than the requirements for the Windows CE Toolkit for Visual C++ 6.0. The Windows CE Platform SDK, Auto PC Edition 1.0 requires a desktop computer with at least a 200 megahertz (Mhz) Pentium class processor running Windows NT 4.0.
To use speech recognition and text-to-speech effectively, use at least a 200 megahertz (Mhz) Pentium class processor, and a PCI-compatible sound card with full duplex capability. Using a slower processor or a sound card that is not PCI-compatible can cause the truncation of speech messages, the termination of the Auto PC emulation environment, the failure to initialize speech recognition, or the failure of speech-enabled applications.
The following features have changed or been added since the beta release of the Windows CE Platform SDK, Auto PC Edition 1.0:
Windows CE Platform SDK, Auto PC Edition 1.0 provides a number of sample applications in the <drive:installation_directory>\WCE201\MS Auto PC\Samples\Win32 directory. The directory for each sample includes a Readme.htm file that describes how to build and run each sample. The following table shows the available samples.
Sample name |
Description |
Formrc | Creates a single form using a constraint based resource script. |
Hello | Demonstrates the basic steps that an application must perform to create a form and show the form on the screen. |
Keyboard | Demonstrates how an application receives messages, including keyboard messages from an Auto PC faceplate and system messages. |
Multform | Demonstrates how to create and manage two different forms, and how use a menu to switch between the two forms. |
Multi_rc | Demonstrates how to create and manage two different forms by using resource scripts instead of creating the forms programmatically. Also demonstrates how use the IASActiveForms interface to switch between the two forms. |
Names | Demonstrates how to use the Address Book API, and how to use a message box. |
Simpleclock | Demonstrates how to implement a message sink for catching keystrokes, using the IASClassMsgSink interface. |
Srapp | Demonstrates how to use speech recognition in your applications. |
Sysinfo | Demonstrates how to create a control panel application for an Auto PC version 1.0. |
Tts | Demonstrates how to use text-to-speech in an application. |
Tuneit | Demonstrates how to use the tuner and audio manager functions to control the radio tuner and audio parameters. |
To simplify the task of creating an Auto PC application that contains all of the required elements, the Windows CE Platform SDK, Auto PC Edition 1.0 provides an Auto PC AppWizard.
Selecting this check box creates an application with two forms and the capability to switch between the forms with a menu.
Selecting this check box generates default help for your application.
Selecting this check box creates a speech object for your application to use.
Selecting this check box enables you to use the tuner API in your application.
Selecting this check box enables you to use the audio manager API in your application.
The WCE Auto PC AppWizard creates the following items:
The application that the wizard creates should compile and run successfully if you perform the following steps before building your application in Visual Studio:
Note If you selected the Help Support check box to create a Help file for your application, you must manually copy the Help (.html) file to the root directory of the emulation object store or to the root directory of your Auto PC. Visual Studio does not download the Help file when you build the project. Use the empfile command to copy the file to the emulation object store, and use Window CE Services to copy the file to your Auto PC.
In addition to using the WCE Auto PC AppWizard, you can also create applications for an Auto PC in Visual Studio by creating a new project.
Choosing A simple Windows CE application in the WCE Application dialog box creates an application that uses a Microsoft Foundation Classes (MFC) header file. Windows CE for the Auto PC does not support MFC, and it also does not support the application that you create when you choose A typical “Hello World!” application in the WCE Application dialog box.
You can now add source files to the project or create new source files. For more information about using the IDE to develop applications, see the online Help for the Windows CE Toolkit for Visual C++ 6.0.
The Windows CE Platform SDK, Auto PC Edition 1.0 includes an emulator that simulates an Auto PC on your desktop computer. You can use the emulator to observe the behavior of an application that you are developing for an Auto PC without having to download the executable files to your Auto PC.
When developing an application for an Auto PC, you can test and debug your application more easily by using the Auto PC emulator. Using the emulator to test your application is more efficient in the early stages of application testing, but the emulator possesses some limitations. You should test your application on an Auto PC during the final stages of application development. Testing on an Auto PC ensures that all parts of your application function appropriately, including those parts that rely on APIs and functions that the emulator does not support.
This section discusses the following topics:
Because the Windows CE emulation environment relies on underlying Windows NT capabilities, your application may sometimes function differently in emulation than on an Auto PC. Also, if you use an application programming interface (API) parameter that is not defined in Windows CE, the result can differ on the Auto PC.
The following table shows the Auto PC API functions that provide valid return values but do not perform other actions under emulation.
AAM_EnableSSD | AAM_RegisterCallback |
AAM_EQBandControl | AAM_SelectSource |
AAM_EQPreset | AAM_SSDControl |
AAM_FilterControl | AAM_VolumeControl |
AAM_GetEQCaps | CPMRegister |
AAM_GetNumSources | CPMNotify |
AAM_GetSourceCap | CPMUnRegister |
The following table shows the APIs that emulation does not support, examples of functions or interfaces contained in those unsupported APIs, and the header file that defines the elements of those APIs.
API |
Example Functions or Interfaces |
Header File |
Positioning and Navigation API (PNAPI) | IPosNav | IPosNav.h |
Tool help API | Module32Next, Heap32Next | Toolhelp.h |
The Auto PC emulation environment lets you build and test Windows CE applications on your desktop computer as if they were running on an Auto PC. Testing your application on the emulator is a good way to test the general operation of your application without downloading to the device. The emulation environment consists of an emulated shell and an object store that contains the registry, databases, and files. The directory structure is identical to the object store on an Auto PC device. The emulation environment gives you the look and feel of the Auto PC device; however, there are certain minor differences. Once your application operates as desired in the emulation environment, you should download it to an Auto PC device for final testing.
To run the Auto PC emulator, you need:
Note The Windows CE Toolkit for Visual C++ 6.0 contains the cross-compilers needed for developing binaries that run on Auto PC devices.
Once your application is ready for emulation, you must set up your application to run in the emulation environment:
Specific procedures for these setup steps are covered in the following sections.
You can rebase an application by either adding the rebase command as a post-build step in Visual Studio, or by using the Rebaseuserdll.bat batch file.
The following example shows a rebase command.
c:\DevStudio\VC\bin\rebase -v -d -b 0x01750000 $(OUTDIR)\$(TARGETNAME).dll
You can specify multiple DLLs on the command line.
The Rebaseuserdll.bat batch file rebases DLLs at 0x01750000. You cannot use the batch file to rebase DLLs from another address. It calls the rebase command with some parameters, as follows:
rebase -d -b 0x01750000 %1 %2 %3 %4 %5 %6 %7 %8 %9
Note When rebasing multiple DLLs that you plan to use simultaneously, rebase the DLLs all at once by including them in the same rebaseuserdll command.
Environment variable |
Value |
include | \WCE201\MS Auto PC\include in your installation directory. |
lib | \WCE201\MS Auto PC\lib\x86em in your installation directory. |
Note You can run Restenv.bat to restore your previous path.
The Windows CE Platform SDK may have set these environment variables for you. If you are using Visual C++, then add the Visual C++ library directory to the lib environment variable, or run the Visual C++ VCVARS32.bat file before you compile and link your application.
Otherwise, specify your executable entry point as either WinMainStartup, or WinMainCRTStartup if you want cinit() called. You can specify the entry point by passing the -entry:WinMainCRTStartup switch to the linker.
The emulation libraries are listed below. Only Corelibc.lib and Coredll.lib are required. Link to the libraries to support additional features, such as COM or particular APIs.
Library |
Provides emulation for |
Abapi.lib | Address book API support |
Apcdll.lib | Required for miscellaneous Auto PC functions |
Asfc.lib | Forms manager, required for all applications with a user interface(UI) |
Asfcguid.lib | Forms manager and control GUIDs |
Commctrl.lib | Windows CE Common controls |
Coredll.lib | Required |
Corelibc.lib | Required |
Msgstore.lib | Required to access message store |
Ole32.lib | Required to support COM and OLE |
Oleaut32.lib | Required to support COM and OLE |
Tuner.lib | Tuner |
Uuid.lib | Windows CE GUIDs |
Winsock.lib | Socket support |
All Auto PC applications that use a UI should link, at a minimum, to the following libraries:
apcdll.lib |
asfc.lib |
asfcguid.lib |
Coredll.lib |
Corelibc.lib |
Ole32.lib |
Oleaut32.lib |
uuid.lib |
If you want to build an application for emulation from the command prompt, you need to export the project as a makefile from Visual Studio first.
set include="C:\Windows CE Tools\wce201\MS Auto PC\include";%include%
set lib= "C:\Windows CE Tools\wce201\MS Auto PC\lib\x86em";%lib%
nmake /F projectname.mak CESubsystem=windowsce,2.01 CEVersion=201
This command creates a .exe file for your project.
To install your application to the emulation environment, you copy your application files to the object store. You must do this if you are using the Windows CE Platform SDK. If you are using the Windows CE Toolkit for Visual C++ 6.0, your files are copied automatically to the root directory of the object store.
You must also register any controls your application uses.
empfile -p:platform_number -c <path>\<file_name>.exe wce:\windows
empfile -p:platform_number -c <path>\<file_name>.dll wce:\windows
Specify a fully-qualified path for your files. These commands copy your files into the \Windows directory of the Auto PC emulation environment object store.
The -p option specifying the platform number is required when using empfile for Auto PC emulation, and you must list this option as the first option on the command line. You can determine the platform number for Auto PC emulation by using the empfile command without any arguments. The usage message that appears includes a list of the platform numbers for each platform. The platform number for Auto PC emulation varies depending on the other emulation environments you have installed on your computer.
Common empfile options are given in Empfile Commands.
Note Auto PC emulation uses a virtual drive to contain the emulation object store. Do not use Windows NT Explorer or the command prompt to manipulate the virtual drive that contains the emulation object store. Use only empfile or Windows CE Remote File Viewer to manipulate the directory structure and files on the virtual drive.
regsvrce [/u | /s] dll_file_name
The /u switch deregisters the DLL, and the /s switch runs Regsvrce.exe silently.
There are several common empfile commands you may need to use in the Auto PC emulation environment. For more information on empfile, run empfile from the \emulation\bin directory with the /? switch.
To do this |
Use this empfile command line switch |
Copy files | -c src_filespec dst_filespec |
Delete files | -d wce_filespec |
Check if a file exists | -e wce_filespec |
Run a program | -r wce_filespec |
Note When specifying file names for the wce_filespec variable, you must provide Windows CE file specification in the form of wce:\filename. When copying files, you must specify one of either src_filespec or dst_filespec as a Windows CE file specification. You can only use wildcards in src_filespec, and only if src_filespec is not a Windows CE file specification.
You cannot run a program with arguments by using the empfile -r command.
To run an application in the emulation environment, you must first configure Auto PC emulation.
Note You can download your files and run your application from within the Visual Studio integrated development environment (IDE). Be sure to set the active project configuration to either Win32 (WCE x86em) Debug or Win32 (WCE x86em) Release and the active Windows CE configuration to Auto PC 2.01 when using the IDE to download files and run applications in emulation. For more information about using the Visual Studio IDE to download and run applications, see the online Help for the Windows CE Toolkit for Visual C++.
You can use the Visual Studio IDE to debug an application. Be sure to set the active project configuration to Win32 (WCE x86em) Debug and the active Windows CE configuration to Auto PC 2.01 when using the IDE to debug applications in emulation. For more information about using the Visual Studio IDE to debug applications, see the online Help for the Windows CE Toolkit for Visual C++.
The Auto PC SDK emulation environment provides three debugging options: None, Console, and OutputDebugString. These options can be set from the Configuration menu by selecting File System. Consult the following table for the function of each option.
Configuration Option |
Result |
None | Nothing done with the debugging output. |
Console | Select to direct debug information to the individual console window of applications running under emulation(including filesys and device). |
OutputDebugString | Check to have all debug information sent to the active debugger, such as the Visual Studio IDE. To view this output while debugging an Auto PC application in Visual Studio, choose Output from the View menu, then choose the Debug tab on the output window that appears. |
Debugging output now appears on the Debug tab of the Microsoft Visual C++ output window. The debugging output does not appear in the Windows CE Debug Console window. For information about shutting down the emulator when using the OutputDebugString option, see Shutting Down the Emulator.
When using the OutputDebugString debugging option, you need to stop the debugger as well before shutting down Auto PC emulation.
This will terminate all emulation apps!
The system has been halted.
-Or-
Choose No in the Microsoft Visual C++ dialog box if you do not want to save the workspace for the debugging session.
This procedure closes both the Auto PC Emulation window and the Microsoft Visual C++ window.
If you have an Auto PC, you can build your applications and download them to your Auto PC for testing by using the Visual Studio IDE on your desktop computer. To download applications with the IDE, you must establish a serial connection between your desktop computer and your Auto PC.
All version 1.0 Auto PCs have a Compact Flash slot. You can use a special serial I/O Compact Flash card and a serial cable to connect an Auto PC with your desktop computer. To use this serial connection, however, you must set up your desktop computer and Auto PC appropriately.
The following procedures provide more information on the steps of the previous procedure.
You are now ready to connect your desktop computer to your Auto PC.
-Or-
Double-click the Mobile Devices icon on your desktop computer.
You can use the Visual Studio IDE to download files to an Auto PC, and to run and debug applications on an Auto PC. Before building a project for an Auto PC, be sure to set the active project configuration to either Win32 (WCE SH3) Debug or Win32 (WCE SH3) Release and the active Windows CE configuration to Auto PC 2.01. The IDE automatically downloads to the Auto PC after building the project. You can run and debug your application as you would in the emulation environment. For more information about running and debuging applications from within the Visual Studio IDE, see the online Help for the Windows CE Toolkit for Visual C++.
The Microsoft Windows CE Platform SDK, Auto PC Edition 1.0 includes an application called CEIBuild that allows you to produce a CEI file that installs your application to an Auto PC. To use CEIBuild, run <drive:installation_directory>\WCE201\MS Auto PC\support\CEI Build\Ceibuild.exe. For more information about CEIBuild, see the Readme.txt file in the <drive:installation_directory>\WCE201\MS Auto PC\support\CEI Build or see “Preparing an Application for Distribution” in the online Help.
You should know about the issues discussed in the following sections before using the Windows CE Platform SDK, Auto PC Edition 1.0.
Emulator does not work properly on a dual processor desktop computer
The Auto PC emulator does not work properly on a dual processor desktop computer. To use the emulator on such a computer, turn one of the processors off before starting the emulator.
Emulator runs only when installed on a local disk
If you try to run the emulator over a network, you receive an error that the file system service is not properly installed. You must install and run the emulator on a local disk.
Memory information option in the About Auto PC control panel application does not properly display the amount of memory used by applications
If you use the About Auto PC application in the control panel or Setup application, and then check the memory usage by selecting the Memory Information option, the memory slider control indicates that Auto PC applications are not using any memory. Because a desktop computer has more memory than an Auto PC, you should check that any application you test under emulation does not use more memory than is available on an Auto PC.
Incorrect screen height and screen width values retrieved by the IfmSystem::GetFormDisplayCaps method
If you call IfmSystem::GetFormDisplayCaps method with the nIndex parameter set to the HORZSIZE or VERTSIZE flags, you always retrieve values of 64 millimeters (mm) for the width of the physical screen and 60 mm for the height of the physical screen, regardless of the actual size of the screen.
Speech recognition available only for the Cancel button in a message box with Abort, Retry, and Cancel buttons
No speech recognition templates are available for the words “abort” or “retry.” If your application creates a message box that contains Abort, Retry, and Cancel buttons, only the Cancel button has a speech command associated with the button.
Administrative privileges required to use Auto PC emulation
You must have administrative privileges to start Auto PC emulation on a desktop computer that runs the Windows NT operating system. Auto PC emulation makes several changes to the system registry that require you log to on as an administrator when starting emulation. Starting emulation without administrative privileges causes the emulator to fail to start, and produces the following error: “Error: the file system service is not installed properly.”
The Windows NT User Manager application allows you to grant administrative privileges to yourself or other users. For more information on granting user privileges, consult the Windows NT documentation.
Using color in Auto PC applications
Auto PC version 1.0 supports eight colors. The following table lists these colors and the corresponding red, green, blue (RGB) values.
Color |
RGB Value |
Black | RGB(0, 0, 0) |
Blue | RGB(0, 0, 255) |
Cyan | RGB(0, 255, 255) |
Green | RGB(0, 255, 0) |
Red | RGB(255, 0, 0) |
Violet | RGB(255, 0, 255) |
White | RGB(255, 255, 255) |
Yellow | RGB(255, 255, 0) |
A bitmap or palette from a Win32-based application is mapped to the eight-color palette shown above when you use the bitmap or palette on an Auto PC. When using bitmaps from Win32-based applications, either use eight-color bitmaps or use the resource editor in Visual C++ to redraw the bitmap using the eight-color palette.
Calling the SetSystemTime and SetLocalTime functions from within emulation does not change the time on the desktop computer
If you use emulation to run an application that calls the SetSystemTime or SetLocalTime function, the application does not change the time on the desktop computer. Even though these functions do not change the time in this case, the functions do not return an error.
MailGetFolderID function does not retrieve correct folder identifier
The MailGetFolderID function returns a folder identifier equal to 0, rather than the correct folder identifier. To work around this problem, use the following code example when creating a folder.
nFolderCheckID = nFolderID = MAIL_FOLDER_NEWS;
bRet = MailGetFolderName( m_hMail, &nFolderCheckID, &nLen, szName );
if (!bRet)
{
bRet = MailPutFolder( m_hMail, nFolderID, szName);
}
Opening Auto PC resource scripts
Many Auto PC resource scripts use constraint-based layout, including many of those used in the sample applications. You should exercise caution when opening such resource scripts in Visual Studio.
Adding a file to a CEI file changes the date and time listed for the file in the Modified field of Windows NT Explorer
If you add a file to a CEI file using CEIBuild, CEIBuild adds a version number to the added file. Because CEIBuild modifies the file in this way, the date and time listed for the added file in the Modified field of Windows NT Explorer changes to reflect the date and time at which you added the file to the CEI file.
Dialog boxes appear when starting or stopping emulation
Auto PC emulation behaves differently than an Auto PC when you start or stop emulation. Dialog boxes appear when emulation starts or shuts down. Also, if the emulator encounters a major system error, a dialog box appears and displays the following text:
System was not shut down cleanly last time. Will try to
clean up before restarting. Press OK to continue.
If the emulator cannot recover from the error, another dialog box appears and displays the following text:
Unable to Clean System, Please Reboot
If this latter dialog box appears, you may need to reboot your machine before you can successfully restart Auto PC emulation.
Projects created for platforms other than Auto PC cannot target the Auto PC platform
To target an application to an Auto PC, you must create a new project by using the WCE Auto PC AppWizard. If you try to use a project created for another platform and then change the active configuration to Auto PC by choosing Set Active WCE Configuration from the Build menu, the compiler generates the following error when building the project:
fatal error RC1015: cannot open include file 'afxres.h'
IASControl::get_Left and IASControl::get_Top methods always retrieve a value of 0 for a form
If you try to set the position of the left edge or top edge of a form by using the IASControl::put_Left or IASControl::put_Top methods, and then use the IASControl:get_Left or IASControl::get_Top methods to retrieve those coordinates, the latter methods retrieve a value of 0 rather than the value that you set with the put_* methods. This behavior occurs because forms always fill the region they occupy, and because the IASControl::SetBounds method is ignored for forms.
Do not use the Windows NT Task Manager to stop Nk.exe or Apchw.exe after halting emulation
Nk.exe and Apchw.exe sometimes continue running after you close Visual Studio and halt emulation. Do not use the Windows NT Task Manager to stop these processes, but wait for them to time out instead. If you use the Task Manager to stop those processes, your computer stops functioning and you can only restart the computer with a cold boot. The processes take approximately five to six minutes to time out. When one these processes times out, a dialog box containing the following text appears:
NK.exe - Cancel Timeout.
The driver \driver\apchook failed to complete a cancelled i/o request in the allotted time
After this dialog box appears, restart your computer before trying to restart the emulator.
Do not start multiple emulation sessions
You cannot, under most circumstances, run more than one emulation session at a time under Windows NT. You can, however, start an Auto PC emulation session, and then start a session for a different emulator while Auto PC emulation continues to run. Running the Auto PC emulator while also running another emulator can cause unpredictable behavior, especially when building projects in the Visual C++ integrated development environment (IDE). Close all emulation sessions before beginning a new emulation session.
Empfile -c command does not work if you specify a quoted path ending with a backward slash
If you want to use the empfile -c command while specifying a path that you must surround by quotes, do not end the path with a backward slash (\). If you use a path that ends with a backward slash and surround the path with quotes, empfile produces the following error text:
failed, path not found
Leave the final backward slash off the path when using a quoted path as part of the empfile -c command.
You cannot use the Windows NT Sound Recorder while running Auto PC emulation
If you try to use the Windows NT Sound Recorder while running Auto PC emulation, you receive the following error:
Another application is recording audio. Stop recording with this
other application and then try to record with Sound Recorder again.
Auto PC emulation uses a component of the Sound Recorder for speech recognition, so you must exit emulation before you can use the Sound Recorder.
Use the PTT key only to wake up the speech recognition system under emulation
Text-to-speech (TTS) sometimes remains active after completing speech output, displaying a blue line along the top of the faceplate image. You cannot use the “Auto PC” wake-up word while TTS remains active, but must instead press the PTT key to wake up the speech recognition system.
WCE Static Library Wizard cannot target an Auto PC
You cannot use static libraries, which you create in Visual Studio with the WCE Static Library Wizard, in Auto PC applications. Static libraries are not compatible with an Auto PC.
Auto PC does not support the LoadAccelerators function
The Windows CE-based LoadAccelerators function allows you to map menu commands to single or combination key commands. Because the Auto PC does not use a keyboard, you should not use the LoadAccelerators function in Auto PC applications.
Configuring WAV files with CEIBuild
If you want to use CEIBuild to install a WAV file that plays when you select the shell icon for an application, you must also use also CEIBuild to set some registry key values. If you do not set these registry key values, TTS reads the name of the application when you select the icon for the application.
CEIBuild not supported for Auto PC emulation
The CEIBuild application, which creates CEI files used to install applications on an Auto PC, does not support the creation of CEI files containing executables that target Auto PC emulation. For this release, CEIBuild only supports executables that target the Hitachi SH3 processor.
Navigational arrows state flags not included in header files
The online Help for the IASUserNavArrows::get_NavState and IASUserNavArrows::put_NavState methods lists flags that describe the possible states of the navigational arrows. The header files included with the Windows CE Platform SDK, Auto PC Edition 1.0 do not define these flags. Use the values that the online Help lists for these flags instead when setting or retrieve the state of the navigational arrows.
WaveInOpen function fails if you set the Wakeup Word option to On or the Listen For option to Always
If you set the Wakeup Word option to On or if you set the Listen For option to Always, the waveInOpen function fails with a return value of MMSYSERR_ALLOCATED. To use the waveInOpen function, set the Wakeup Word option to Off and the Listen For option to anything other than Always.
Functions for using the critical process monitor will be updated
The functions that allow you to use the critical process monitor, CPM*, will be substantially changed for version 2.0. If you need to use these functions in an application, you should verify that the your target device supports these functions and that the functions work as you expect the functions to work.