Pocket PC services: Creation, deployment and debugging

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.

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 solve 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.

Creating Service DLL

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_Writeb

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 defines 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 application needs user can put some logic to the other MYS_... methods in the same manner.

Service Registration in Registry

In order to have service automatically started at system startup you should add an arbitrary named subkey to the registry HKEY_LOCAL_MACHINE\Services\MyService key (Service key is the name of the service, user can use there other names also) 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) files 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.

[HKEY_LOCAL_MACHINE\Services\MyService]

"Dll"="MYS.dll"

"Order"=dword:8

"Keep"=dword:1

"Prefix"="MYS"

"Index"=dword:0

"Context"=dword:0

"DisplayName"="Sample Service"

"Description"="Sample Service"

User can create a C # application to register the service DLL.

Installing Pocket PC Service

To install a service you should copy your service DLL into the \Windows folder. From eVC IDE select the Pocket PC 2003 device as target platform and build the project, it will deploy the DLL into \Windows folder. For some devices while deploying the IDE may show “CE Platform PocketPC 2003 does not match remote OS version 421. Continue?” error message, neglect the warning and press “Yes”.

Start Service

Once the service is installed and registered, the PDA need to be restarted to start the service DLL.

C# code to start and stop the service DLL

Sometimes user may need to start or stop the service from code, such as backup service where before creating the backup or restoring it, we may pause the service.

[DllImport("coredll")]

private extern static int ActivateService(string lpszDevKey, int dwClientInfo);

[DllImport("coredll")]

private extern static int GetServiceHandle(string szPrefix, string szDllName, int pdwDllBuf);

[DllImport("coredll")]

private extern static bool DeregisterService(int hDevice);

Above are the declarations for the API functions that would require activating and deactivating the service.

If you want to deploy modified version of already deployed and running DLL, before deploying the new DLL, services.exe should be terminated because it won’t allow replacing existing DLL in running mode. To kill services.exe the steps are.

1. From eVC Tools menu select Remote Process Viewer.
2. Select your device from Select the Device popup.
3. Select the Services.exe from Services section.
4. Click Kill Process (X) button on the toolbar.

Activate the Service

int handle = ActivateService(“MyService”, 0);

The above code starts the service DLL.

First parameter is registry entry of the service; here it is “MyService”.

Second parameter is reserved and it should be Zero.

Stop the Service

int handle = GetServiceHandle ("MYS" + "0:", null, 0);

DeregisterService (handle);

GetServiceHandle function returns the handle of the service DLL.

The first parameter is the prefix of the service with index number; here prefix is “MYS” and index number is “0”

Second parameter is optional that contains the name of the service DLL.

Third parameter is also optional specifies the number of bytes written or the number of bytes required if the buffer is not large enough.

DeregisterService stops the instance of the service provided as handle.

Debugging Pocket PC Service

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 process you need a local copy of the services.exe file. The user can copy the services.exe from the /Windows folder of PDA.

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 debugger loop for each service DLL in services.exe as soon as it ask for local copy of your DLL, provide the local copy of DLL.
10. It will take some time (can be from few seconds to few minutes) to reach the code still breakpoint in the service DLL.
11. Start debugging.