By Victor Sharov, February 26, 2004.
Print version

Summary

Often Pocket PC programs need a background process and most of existing Pocket PC programs implement it by creating an executable file which is started during system start-up. But Pocket PC has 32 processes limit and having many different programs running in background can be a serious problem. Pocket PC 2003 provides special mechanism implemented in Services.exe that allows Pocket PC developers to shape their background applications into services that run in one process as different threads. This article describes creating Pocket PC services, distributing them and gives a solution to run services on Pocket PC 2000 and 2002 platforms.

Table of Contents

1. What You Need
2. Introduction
3. Creating Service DLL
   1. Creating Service DLL Using MFC
   2. Creating Service DLL Without MFC
4. Service Registration in Registry
5. Distributing Services.exe for Pocket PC 2000/2002
6. Installing Service
7. Debugging Pocket PC Services
8. Samples
9. Conclusion

• Microsoft eMbedded Visual C++ 3.0
• Services.exe for Pocket PC 2000 and Pocket PC 2002
• SampleServiceMFC.zip - sample service written using MFC
• SampleService.zip - sample service written without MFC

Many Pocket PC applications need a background process. For example:

• A program that shows a window when SD card is inserted
• A permanent backup program
• A program that control GPRS traffic
• A Web server
• A program that adds a special icons to the taskbar

Now almost all Pocket PC developers create an executable file and put shortcut to this file to \Windows\StartUp so this program is started just after reset and runs in background. This approach has a serious problem because number of processes in Windows CE is limited by 32. For example in XDA II Pocket PC devices there are 28 processes running just after soft-reset. If you install 2-3 third-party programs that need background process you will have only 1-2 processes for running programs!

Microsoft has introduced a solution for this problem in Windows Mobile 2003. Windows Mobile 2003 supports services which are DLLs run in one process (services.exe) as different threads. It solves the problem but:

1. Most Pocket PC developers do not know about this technology.
2. Services are not properly documented. For example you will not find necessary headers in Pocket PC 2003 SDK.
3. This technology is not supported on Pocket PC 2000 and Pocket PC 2002. So you cannot use services if you want to create programs that will work on both Pocket PC 2002 and Windows Mobile 2003 for Pocket PC.

This article describes how to solves these problems and how to create and distribute services for Pocket PC that will work on all Pocket PC versions.

Pocket PC service interface is similar to Pocket PC driver interface. Pocket PC service is a DLL that should export a set of functions and services.exe process loads these DLLs and initializes them by calling one of the functions.

This article is an appeal to Pocket PC developers Use services for background tasks!.

The following steps are to be taken in order to implement an MFC-based service:

1. In Microsoft eMbedded Visual C++ create new WCE MFC AppWizard (dll) project
2. Add exported functions definitions (you should use your own prefix instead of MYS): extern "C" DWORD PASCAL EXPORT MYS_Close(DWORD dwData) { AFX_MANAGE_STATE(AfxGetStaticModuleState()); return 0; } extern "C" DWORD PASCAL EXPORT MYS_Deinit(DWORD dwData) { AFX_MANAGE_STATE(AfxGetStaticModuleState()); return 0; } extern "C" DWORD PASCAL EXPORT MYS_Init(DWORD dwData) { AFX_MANAGE_STATE(AfxGetStaticModuleState()); return 1; } extern "C" DWORD PASCAL EXPORT MYS_IOControl( DWORD dwData, DWORD dwCode, PBYTE pBufIn, DWORD dwLenIn, PBYTE pBufOut, DWORD dwLenOut, PDWORD pdwActualOut) { AFX_MANAGE_STATE(AfxGetStaticModuleState()); return 1; } extern "C" DWORD PASCAL EXPORT MYS_Open( DWORD dwData, DWORD dwAccess, DWORD dwShareMode) { AFX_MANAGE_STATE(AfxGetStaticModuleState()); return 0; } extern "C" DWORD PASCAL EXPORT MYS_Read( DWORD dwData, LPVOID pBuf, DWORD dwLen) { AFX_MANAGE_STATE(AfxGetStaticModuleState()); return 0; } extern "C" DWORD PASCAL EXPORT MYS_Seek( DWORD dwData, long pos, DWORD type) { AFX_MANAGE_STATE(AfxGetStaticModuleState()); return 0; } extern "C" DWORD PASCAL EXPORT MYS_Write( DWORD dwData, LPCVOID pInBuf, DWORD dwInLen) { AFX_MANAGE_STATE(AfxGetStaticModuleState()); return 0; }

   MYS here is a prefix that is to be specified further by application calls to Services.exe (here MYS stands for MY Service).

   Note: as this DLL will be dynamically linked any functions exported from this DLL which call into MFC must have the AFX_MANAGE_STATE macro added at the very beginning of the function. It is very important that this macro appear in each function, prior to any calls into MFC. This means that it must appear as the first statement within the function, even before any object variable declarations as their constructors may generate calls into the MFC DLL. Please see MFC Technical Notes 33 and 58 for additional details.

3. Add these functions names to your project .def file export table (you should use your own prefix instead of MYS): EXPORTS ; Explicit exports can go here MYS_Close MYS_Deinit MYS_Init MYS_IOControl MYS_Open MYS_Read MYS_Seek MYS_Write

4. This is now time to add some specific initialization code to MYS_Init function.

   Most likely you need to create a new thread here that will encapsulate all service logic. Define thread controlling function to do that. That function is the right place to create additional windows, timers or any other application-specific needs. In the sample given we create a timer and run thread message loop.

   UINT MyControllingFunction( LPVOID pParam ) { theApp.m_nTimer = SetTimer(0, 0, 10 * 1000, MyTimerProc); MSG msg; while (GetMessage(&msg, 0, 0, 0)) { TranslateMessage(&msg); DispatchMessage(&msg); } return 0; } extern "C" DWORD PASCAL EXPORT MYS_Init(DWORD dwData) { AFX_MANAGE_STATE(AfxGetStaticModuleState()); theApp.m_pThread = AfxBeginThread( MyControllingFunction, 0); return 1; }

   Be sure to return non-zero value from MYS_Init function as zero return value indicates service initialization failure and causes service DLL to be unloaded immediately.

   Depending on your application needs you can put some logic to the other MYS_... methods in the same manner.

The following steps are to be taken in order to implement an MFC-based service:

1. In Microsoft eMbedded Visual C++ create new WCE Dynamic-Link Library project
2. Add exported functions definitions (you should use your own prefix instead of MYS): DWORD MYS_Close(DWORD dwData) { return 0; } DWORD MYS_Deinit(DWORD dwData) { return 0; } DWORD MYS_Init(DWORD dwData) { return 1; } DWORD MYS_IOControl( DWORD dwData, DWORD dwCode, PBYTE pBufIn, DWORD dwLenIn, PBYTE pBufOut, DWORD dwLenOut, PDWORD pdwActualOut) { return 1; } DWORD MYS_Open( DWORD dwData, DWORD dwAccess, DWORD dwShareMode) { return 0; } DWORD MYS_Read( DWORD dwData, LPVOID pBuf, DWORD dwLen) { return 0; } DWORD MYS_Seek( DWORD dwData, long pos, DWORD type) { return 0; } DWORD MYS_Write( DWORD dwData, LPCVOID pInBuf, DWORD dwInLen) { return 0; }

   MYS here is a prefix that is to be specified further by application calls to Services.exe (here MYS stands for MY Service).

3. Add these functions names to your project .def file export table (you should use your own prefix instead of MYS): EXPORTS ; Explicit exports can go here MYS_Close MYS_Deinit MYS_Init MYS_IOControl MYS_Open MYS_Read MYS_Seek MYS_Write

4. This is now time to add some specific initialization code to MYS_Init function.

   Most likely you need to create a new thread here that will encapsulate all service logic. To do this define thread controlling function. That function is the right place to create additional windows, timers or any other application-specific needs. In the sample given we create a timer and run thread message loop.

   unsigned long __cdecl MyControllingFunction( LPVOID pParam ) { g_nTimer = SetTimer(0, 0, 10 * 1000, MyTimerProc); MSG msg; while (GetMessage(&msg, 0, 0, 0)) { TranslateMessage(&msg); DispatchMessage(&msg); } return 0; } DWORD MYS_Init(DWORD dwData) { HANDLE hThread = CreateThread( 0, 0, MyControllingFunction, 0, 0, 0); return 1; }

   Be sure to return non-zero value from MYS_Init function as zero return value indicates service initialization failure and causes service DLL to be unloaded imediately.

   Depending on your application needs you can put some logic to the other MYS_... methods in the same manner.

   Please refer to Pocket PC services article to learn how to register your service to be started at system startup and how to start it programmatically. Please refer to MSDN Windows CE .NET 4.2 for further details.

In order to have service automatically started at system startup you should add an arbitrary named subkey to the registry HKEY_LOCAL_MACHINE\Services\Service key and specify the following values:

Order : REG_DWORD

Order in which Services.exe will load each service. The service with the lowest order is loaded first.

Dll : REG_SZ

Dynamic-link library (DLL) file to be loaded. Only file name without path. This DLL should be located in \Windows folder.

Keep : REG_DWORD

Must be 1 for services that should run in background, if Keep = 0, the DLL will be unloaded immediately after initialization.

Prefix : REG_SZ

Prefix of your functions exported from the service DLL (instead of xxx in xxx_Init, etc). Must be 3 symbols.

Index : REG_SZ

Service index (set to 0).

DisplayName : REG_SZ

Display service name.

Description : REG_SZ

Description of display service.

Context : REG_DWORD

Initial value passed into the initialization routine (must by 0).

For example, for the Sample MFC-based service to start as a service at boot time, the following registry key should be used.

Most probably you will write these values to registry in your installer using .inf file. Here is code for .inf file:

Please refer to MSDN Windows CE .NET 4.2 for details.

Windows Mobile 2003 for Pocket PC already includes servies.exe but if you want your program that implements a service runs on Pocket PC 2000 or Pocket PC 2002 you should distribute service.exe yourself.

This article contains service.exe implementation by Spb Software House that you can include in your installer. It scans the registry and loads registered services just after reset. It also provides functions to load/unload services but it does not implement functions for writing/reading to/from the service.

It is critically important for Pocket PC users that all services are run in one process and that all third-party developers use the same program on Pocket PC 2000 and 2002 to run services so we strongly recommend using the method described bellow.

To add Pocket PC 2002 support to your program that uses a service you should distribute services.exe with your program. Install services.exe to your local program folder and then check in setup.dll if installing services.exe is needed (it is needed for Pocket PC 2000 and 2002) and if needed copy it to \Windows folder:

1. Include services.exe into your CAB file. Install this file to your program folder (something like \Program Files\MyProgram\services.exe).
2. Add the following code to Install_Exit function of your setup.dll file (read more about using setup.dll in Pocket PC installers): BOOL InstallServiceManagerIfNeeded(LPCTSTR pszInstallDir) { //We do not need to install services.exe if Pocket PC 2003 or later OSVERSIONINFO osVer; GetVersionEx(&osVer); if (osVer.dwMajorVersion >= 4) { return FALSE; } //We do not need to install services.exe if it already exists WIN32_FIND_DATA wfd; HANDLE hFile = FindFirstFile(_T("\\windows\\services.exe"), &wfd); BOOL bExists = (hFile!=INVALID_HANDLE_VALUE); FindClose(hFile); if (bExists) { return FALSE; } //Copy services.exe from the local program folder CString strFilePath = CString(pszInstallDir) + _T("\\services.exe"); if (!::CopyFile(strFilePath, _T("\\windows\\services.exe"), TRUE)) { //Error. File is not found return FALSE; } //Create shortcut in the autorun folder, so services.exe will be started after soft-reset TCHAR szStartupFolderPath[MAX_PATH]; ::SHGetSpecialFolderPath(NULL, szStartupFolderPath, CSIDL_STARTUP , FALSE); CString strShortcutPath = CString(szStartupFolderPath)+_T("\\Services.lnk"); ::SHCreateShortcut((LPTSTR)(LPCTSTR)strShortcutPath, _T("\\Windows\\Services.exe")); //Run servies.exe PROCESS_INFORMATION pi; ::CreateProcess( TEXT("\\windows\\Services.exe"), NULL, NULL, NULL, FALSE, 0, NULL, NULL, NULL, &pi); return TRUE; }
3. Run InstallServiceManagerIfNeeded(LPCTSTR pszInstallDir) from your Install_Exit function in Setup.dll.
4. Do not forget that you should start your service after that by calling STStartService function.

To install a service you should copy your service DLL into the \Windows folder and start this service from Install_Exit function in Setup.dll. Do not forget to stop the service before uninstalling your program (in Uninstall_Init function of your Setup.dll).

Step by step:

1. Include your service DLL into your .inf file and install it to \Windows folder
2. Add lines into your .inf file to register your service in the registry: (read more in Service Registration in Registry ) [RegSettings.All] HKLM,Services\MyServ,Dll, 0x00000000,MYS.dll HKLM,Services\MyServ,Prefix, 0x00000000,MYS HKLM,Services\MyServ,Order, 0x00010001, 8 HKLM,Services\MyServ,Keep, 0x00010001, 1 HKLM,Services\MyServ,Index, 0x00010001, 0 HKLM,Services\MyServ,Context, 0x00010001, 0 HKLM,Services\MyServ,DisplayName, 0x00000000,Sample MFC Service HKLM,Services\MyServ,Description, 0x00000000,Sample Service demonstratig MFC usage
3. If your program supports Pocket PC 2000 or 2002 then distribute services.exe as it is described in Distributing Services.exe for Pocket PC 2000/2002
4. Start your service after installation your program: #include "SpbServices.h" ... codeINSTALL_EXIT Install_Exit( HWND hwndParent, LPCTSTR pszInstallDir, WORD cFailedDirs, WORD cFailedFiles, WORD cFailedRegKeys, WORD cFailedRegVals, WORD cFailedShortcuts ) { ... InstallServiceManagerIfNeeded(pszInstallDir); STStartService(_T("MyServ")); ... }
5. Stop your service before uninstalling your program: #include "SpbServices.h" ... codeUNINSTALL_INIT Uninstall_Init( HWND hwndParent, LPCTSTR pszInstallDir ) { ... STStopService(_T("MyServ")); ... }
6. You can also stop the service before installing your program to support "upgrade" scenario

To debug your service you can attach to the services.exe process. You have to use the eVC++ 4 debugger for that because the eVC++ 3 debugger does not support attaching to remote processes. To attach the debugger to the services.exe proces you need a local copy of the services.exe file. Unfortunately you cannot copy the services.exe file from Pocket PC 2003 because it is stored in ROM in EXIP format.

But if you have a local copy of Windows Mobile 2003 services.exe you can attach to the services.exe process using the following step-by-step instructions:

1. Open your service project in Microsoft eMbedded C++ 4.0.
2. Add DebugBreak() calls in proper place of your code. (Setting breakpoints in your code will not help.)
3. Build debug configuration and upload your DLL to the device.
4. Add registry values desired as described above.
5. Start your service on the device (e.g. soft-reset).
6. Attach to the services process (Build / Start Debug / Attach to WCE process...).
7. Connect to your device.
8. Select "services.exe" as the process to debug. Browse for your local copy of services.exe binary image.
9. As soon as your service stops at the breakpoint you will be asked for local copy of your service DLL.
10. Start debugging.

Besides that you can use log files (for example STLogFile Library) to trace your program.

On Microsoft Mobile 2000 and 2002 devices you cannot attach to process so tracing with log files is the only way to debug.

• SampleServiceMFC.zip - sample service written using MFC
• SampleService.zip - sample service written without MFC

We strongly recommend using services for background tasks because of 32 process limit imposed by Windows CE. Although Pocket PC 2000 and Pocket PC 2002 do not support services you can add this support using services.exe from this article.

Related resources:

• Article: Going background with window messages