Windows Mobile Pocket PC Smartphone Programming

Pocket PC Power Management Series 11: Play sound (for example, wav file) when a Pocket PC is suspended

2006-05-11T00:09:00.000-07:00

Pocket PC Power Management Series 11: Play sound (for example, wav file) when a Pocket PC is suspended

I am going to write a new series on Pocket PC Power Management topic: How to play sound when Pocket PC is sleeping or suspended. Let me use a simple API to achieve this purpose: PlaySound.

Why care?

If you read my previous series on the Power Management topic, you may ask why we care. If the Pocket PC sleeps, no thread can run, so PlaySound won't even be called. If the PPC is not sleeping, PlaySound is called, so why the hassle? The answer is: Yes, PlaySound will be called, but you may not hear the sound! So the title of this blog is sort of misleading. It should be changed to something like "How to make sure there is a sound when the device is suspended".

Let us say, you write the code to request the PPC to play a wav file, even when it is suspended. A good example is the Alarm program. It might need to play a warning or ringtone at 8PM. This piece of code can be executed at 8PM, guaranteed by Windows CE OS. However, you may be disappointed not hearing any sound. Below I will explain why and how to solve the problem.

Why no Sound?

Ultimately a peripheral device needs to emit the sound. This peripheral must be powered or put into certain state so as to vibrate to produce sound waves. A good chance is: When PlaySound() is called, the Pocket PC is in such a "System Power State" that the sound peripheral is not supposed to work; or in Microsoft terms, the sound peripheral is in such a "Device Power State" mapped from the current "System Power State", that the sound peripheral might have no power, have low power or in standby mode.

For our specific alarm example, the Pocket PC might be in a "System Power State" called "Unattended". The sound peripheral is called "wav1:", which is put into a "D4 Device Power State", mapped from "Unattended" state. "D4" means "No Power", so you won't be able to hear any sound.

To above explanation might be too abstract. If you really need to understand those terms, please read Microsoft Platform Builder documentation on "Power Management".

A Possible Solution

A possible solution to the problem is to change the mapping, so as to change the power state of "wav1:" device. The following code snippet is doing this job:

HRESULT ChangeWav1Mapping()
{
   LRESULT lr = E_FAIL;

   HKEY hKey = NULL;
   DWORD dwSubKeys = 0;
   DWORD dwMaxSubkeyLen = 0;
   TCHAR szSubkeyName[MAX_PATH];

   lr = RegOpenKeyEx(HKEY_LOCAL_MACHINE, TEXT("\\System\\CurrentControlSet\\Control\\Power\\State"), 0, 0, &hKey);
   if (ERROR_SUCCESS != lr) goto FuncExit;

   lr = RegQueryInfoKey(hKey, NULL, 0, 0, &dwSubKeys, &dwMaxSubkeyLen, NULL, NULL, NULL, NULL, NULL, NULL);
   if (ERROR_SUCCESS != lr) goto FuncExit;

   for (int i=0; i<dwSubKeys; i++) {
      DWORD dwSubkeyNameLen = MAX_PATH-1;
      memset(szSubkeyName, 0, MAX_PATH*sizeof(TCHAR));
      lr = RegEnumKeyEx(hKey, i, szSubkeyName, &dwSubkeyNameLen, NULL, NULL, NULL, NULL);
      if (ERROR_SUCCESS != lr) continue;

      //ALERT(szSubkeyName);

      HKEY hSubkey = NULL;
      lr = RegOpenKeyEx(hKey, szSubkeyName, 0, 0, &hSubkey);
      if (ERROR_SUCCESS != lr) continue;

      // any wav1: ?
      DWORD dwValueType = 0;
      DWORD dwValueData = 0;
      DWORD dwValueDataLen = sizeof(DWORD);
      lr = RegQueryValueEx(hSubkey, TEXT("wav1:"), NULL, &dwValueType, (LPBYTE)&dwValueData, &dwValueDataLen);
      if (ERROR_SUCCESS == lr && 0 != dwValueData) {
         dwValueData = 0;
         RegSetValueEx(hSubkey, TEXT("wav1:"), NULL, REG_DWORD, (LPBYTE)&dwValueData, sizeof(DWORD));
      }
      RegCloseKey(hSubkey);
   }

   RegFlushKey(hKey);

FuncExit:
   if (hKey) {
      RegCloseKey(hKey);
   }

   return S_OK;
}

Notice this is a piece of bad code. It forces the "wav1:" device to be always powered, no matter what state the Pocket PC is in. Looks like that is the case for most Pocket PC 2003 devices, but probably not true for Pocket PC 5.0 device. So the above code effectively changes the sound behavior of PPC 5.0 device.

The recommended API to use to SetPowerRequirement and ReleasePowerRequirement. I will talk about them in a later post.

Wrap Up

Pocket PC sleeps. Read the following two posts for basis:

There are ways to force the device not to sleep, or request it to run a program at certain time or upon certain event:

The above techniques force the CPU to run, but not necessarily other peripheral devices. In this post we talked about "wav1:" and a possible hacky way to override the power mapping.

XXX.exe is not a valid Pocket PC Application: Troubleshooting guidelines

2006-05-08T00:08:00.000-07:00

XXX.exe is not a valid Pocket PC Application: Troubleshooting guidelines

It is not uncommon for a developer to see his/her program cannot run in the emulator or physical device, after struggling with code development, compilation error and build issues. Most typical error is like "XXX.exe is not a valid Pocket PC application", like the following screen cut. Hereby I am trying to write simple guidelines for troubleshooting such issue.

1. Check the Platform

The executable might be built for a platform that does not match the target device. For example, an executable built for x86 emulator cannot run in any physical device, which supports ARM instruction sets.

In WM5.0, Microsoft introduces a build target called "THUMB", which is a subset of ARM instruction sets. An executable built for "THUMB" can only run in WM5.0 device or emulator. You'll get the above error message if running such executable in Pocket PC 2003 or Smartphone 2003 device.

The way to check the platform is to use "dumpbin /header ", and take a look at the line exposing the "machine" information.

The way to fix platform issue is to change project settings in your IDE (EVC4 or Visual Studio 2005). Both IDEs allow you to manually modify the command line option /MACHINE.

2. Check the SubSystem

An executable built for a lower subsystem (for example, 4.20) can run in a WM5.0 device, but not vice versa. If you try to start a program built for 5.0, you will get the warning "XXX is not a valid Pocket PC application".

The way to check the subsystem is to use "dumpbin /header ", and take a look at the line exposing the "subsystem" information.

The way to fix subsystem issue is to change project settings in your IDE (EVC4 or Visual Studio 2005). Both IDEs allow you to manually modify the command line option /SUBSYSTEM.

3. DLL HELL

The previous two issues are easy to identify and fix, but the third one is very concealing and hard to troubleshoot. In general, if a program needs DLLs (who does not?), the DLL must either be present in the system, or already loaded into memory. If a required DLL is not available, the warning is clear and to the point: "Cannot find 'XXX.exe' (or one of its components). Make sure the path and file name are correct and all the required libraries are available."

However, if the DLL is available or already loaded into memory, but the DLL does not export the required functions, CE OS could not verify that linker time dependencies are met. It shows a super-misleading warning "XXX.exe is not a valid Pocket PC application".

It is hard to find which DLL causes the issue, and even harder to solve the issue. On the desktop, you can isolate yourself to certain extent by ensuring that the DLL you built and tested is the one that is loaded by the OS; one way putting the DLL in the same directory as your application. On Windows CE, to save memory, only a single copy of DLL is loaded into physical memory, and multiple processes share the single copy if all requiring such DLL.

To confirm whether the DLL HELL causes the dreaded message, you can try to find what other processes are using the same DLL, then terminate those processes and start your first. If your program works, then definitely your issue is caused by the DLL loaded by other processes. MFC is a good suspect, since there is so many versions of MFC DLLs (although Microsoft has taken extra mile to name the MFC DLLs with version number, debug/retail, ...)

Wrap Up

Machine or SubSystem mismatch is easy to detect and fix. Please read "Trap of Copying Project Settings in Visual Studio 2005 (/Machine: ARM vs. Thumb, /subsystem: windowsce, 4.02 vs 5.01)" for more details.

Issue caused by DLL-mismatch is much harder to detect. If you run into the issue, and you are use MFC, there is a high possibility that multiple versions of MFC DLLs are the culprit.

Emulator Troubleshooting/Tip 03: Quickly Establish ActiveSync Connection

2006-05-05T00:06:00.000-07:00

Emulator Troubleshooting/Tip 03: Quickly Establish ActiveSync Connection

As talked in "Emulator Troubleshooting/Tip 01: To Cradle or Not to Cradle?", when an emulator is cradled, ActiveSync uses DMA to communicate with the emulator, eliminating the error-prone TCP/TP transport.

DMA is generally very reliable. However, quite a few times, an emulator might have difficulty to be ActiveSync'ed, after cradled. Typically a dialog like below is displayed.

I was not able to generalize under what circumstances ActiveSync did not work. It might happen if ActiveSync's "Connection Setting" is changed, or the Device Emulator Manager runs several emulators and one of which is already cradled.

At first, I did not know any good way to fix the problem. Restart the emulator does not help at all. Killing ActiveSync or wcescomm.exe might worsen the issue. A lot of times I had to restart the machine.

Accidentally I found a very quick and very reliable way to make ActiveSync connect to the emulator:

1. Go to ActiveSync's "Connect Setting" dialog, and clear the check box "Allow connections to one of the following". Click OK to dismiss the dialog.

2. Again, go to ActiveSync's "Connect Setting" dialog, and check the check box "Allow connections to one of the following". Make sure DMA is chosen. Click OK to dismiss the dialog.

In my cases, a cradled-emulator will be successfully ActiveSync'ed, guaranteed!

A little off-topic: When ActiveSync 4.0 were released, there were so many issues that Microsoft had to publish a special memo to partners, listing all possible workarounds and promising a quick release of ActiveSync 4.1. Actually when I got a PPC6700 device from Sprint before it was released to mass-market, I had so many troubles making ActiveSync 4 work with the device, that the Sprint support recommended me to format and install a new machine, without installing any other software and without enabling any firewall, and dedicate the machine to ActiveSync 4 and the device. What a nice workaround!

Pocket PC Console for standard input and standard output: A convenient tool for lazy debugging and tracing in Pocket PC 2003 devices

2006-05-03T00:44:00.000-07:00

Pocket PC Console for standard input and standard output: A convenient tool for lazy debugging and tracing in Pocket PC 2003 devices

Debugging and tracing sometimes can be a tricky business, especially for a multi-threaded program.

Log file is used most commonly.
OutputDebugString is also nice, and there is no need to write any code to deal with a log file. However, you do need to attach the debugger to receive the debugging message.

Probably the simplest approach, requiring neither a log file nor a debugger, is the famous printf (or the C# equivalent Console.Write, or the Java equivalent System.out.println). The simplicity of using printf, and the beautify of showing messages on a console in real time, make printf a very nice tool for lazy programmers :)

Pocket PC Shell

Unfortunately there is no built-in console (therefore no standard input and standard output) in Windows Mobile devices. Even if your code compiles and builds correctly, there is no way you can see the messages.

One tool coming for rescue is PPC Command Shell, part of Microsoft Windows Mobile Developer Power Toys. See my article "How to launch a program via command line in Pocket PC 2003 device and Pocket PC 5.0 device?" for a brief introduction on those nice little tools.

PPC Command Shell - Command shell for the Pocket PC 2003 device.

Once installed, three files can be found in the desktop PC's destination folder:

console.dll: copying it to the device's \Windows folder
shell.exe: copying it to any folder in the device
cmd.exe: copying it to any folder in the device

The only files needed for printf to work are console.dll and shell.exe. These two provide the console, supporting standard input and standard output. Once invoked, shell.exe stays in the memory. In fact, upon running, shell.exe put an entry under registry HKLM\Init, so as to make sure itself is always up and running (even before the OS kernel components, like device.exe, gwes.exe, and etc.)

[HKEY_LOCAL_MACHINE\init]
"Launch10"="shell.exe"

The executable cmd.exe is not needed. It solely provide implementations of some commonly used DOS prompt commands, for example, dir, cd.

Below is a simple testing program:

printf("This is a test");
MessageBox(NULL, TEXT("Console Test!"), TEXT("Demo"),
 MB_ICONINFORMATION|MB_OK|MB_SETFOREGROUND|MB_OK);

And here is the screen cut when the program runs:

Warning: This tool does not work in Pocket PC 5.0 device, nor does it work in any Smartphone device. In fact, the following warning is popped up if running in Smartphone 2003 device:

Wrap Up

Pocket PC Shell is a simple yet powerful tool for debugging or tracing in real time. However, the one packaged in Microsoft's Mobile Power Toy can only work in Pocket PC 2003 device (inclduing 2003 SE).

There is another free tool but I've never tested it. Looks like it has not been updated for quite a while.

Notice: Never compile printf into your release build! The printf and console processing code are not simple thus sort of eating the CPU!

Trap of Copying Project Settings in Visual Studio 2005 (/Machine: ARM vs. Thumb, /subsystem: windowsce, 4.02 vs 5.01)

2006-04-30T00:30:00.000-07:00

Trap of Copying Project Settings in Visual Studio 2005 (/Machine:ARM vs. Thumb, /subsystem:windowsce,4.02 vs 5.01)

Visual Studio 2005 offers developers with a nice option when a new project platform needs to be created: to copy project settings for one platform to the new platform.

How Copying Project Setting works?

Typical use case is that you already have a project for Pocket PC 2003, and you want to create a new project targeting Pocket PC 5.0 device. You can bring up "Project Settings" dialog, and click "Configuration Manager" button to "New" the project for 5.0 platform, and opt to copy from the project setting for 2003 platform.

Visual Studio takes care quite a few changes automatically, for example, output directory, windows CE version, and PPC/Smartphone platform. The mechanism to cover the changes is using Macros extensively. Below are two typical macros:

Windows CE version difference: $(CEVer). 4.20 for 2003 platform, and 5.01 for 5.0 plaform.
Platform difference: $(CEPlatform) / $(CePlatform) / $(PLATFORMDEFINES). WIN32_PLATFORM_WFSP for Smartphone, and WIN32_PLATFORM_PSPC for Pocket PC.

Issue of Blindly Copying Project Settings from Newer Platform to Older Platform

It is worthy noting that VS2005 does not adjust two important options for its linker while copying project settings:

/SUBSYSTEM option, which tells the targeting OS how to run the .exe file, and affects the entry point symbol (or entry point function) that the linker will choose.
/MACHINE option, which specifies the target platform for the program, for example, X86, X64, IA64, MIPS, SH4, and etc.

If you create a new Smart Device project, possibly /MACHINE is not set explicitly, and /SUBSYSTEM is hard coded to be the number most suitable for the project. For example, if you create a project for Pocket PC 5.0 platform, /MACHINE is not set (so default to THUMB), and /SUBSYSTEM is set to 5.01.

If such settings are blindly copied to another project for older platform (in this case, Pocket PC 2003), the final binary won't be executed by PPC2003 device.

Walkthrough of the issue

1. A new solution is created, and a new Smart Device project targeting Pocket PC 5.0 platform is created.

"Project Setting"=>"Linker"=>"System"=>"SubSystem" is not set.
"Project Setting"=>"Linker"=>"Advanced"=>"Target Machine" is not set either.

Command line option will be like " /subsystem:windowsce,5.01"

Do a "dumpbin /all" on the executable generated by VS2005, you'll see something like this, meaning the binary is for Thumb machine and CE version should be 5.01 or higher.

FILE HEADER VALUES
 1C2 machine (Thumb)
OPTIONAL HEADER VALUES
 5.01 subsystem version

2. The executable for Pocket PC 5.0 runs great in a 5.0 device. Now you want propagate its success to Pocket PC 2003 devices, so a new project targeting PPC2003 platform is created using Configuration Manager. In its "Active solution platform" dropdown list, you select "New", and "Copy settings from" the Pocket PC 5.0 platform.

3. For the new project to build, you may need to add "secchk.lib" to lib dependency list if you have at least one function call, and add "ccrtrtti.lib" to lib dependency list if you have at least one C++ source file. However, if you run the executable, you'll get the infamous error dialog:

4. Do a "dumpbin /all" on the executable for PPC2003 platform, you'll see that the executable is for THUMB machine and CE OS must be 5.01 or higher, exactly the same as the one for PPC5.0 device. To fix it, you need to change the linker option to something like " /subsystem:windowsce,4.20 /machine:ARM".

Rebuild and you'll get a good executable with the following header values:

FILE HEADER VALUES
 1C0 machine (ARM)
OPTIONAL HEADER VALUES
 4.20 subsystem version

Notice you must change both /subsystem and /machine, otherwise it won't work!

Wrap Up

VS2005 seems to copy the project setting literally. It resolves the fundamental differences (OS, PPC or Smartphone, directories) by expanding Macros, for example, $(CEVer) and $(CEPlatform). However, /MACHINE and /SUBSYSTEM are either not specified, or hard-code to be a number, resulting in wrong values to be used in the newly-created project. Such mismatch probably is not a big issue if the new project is for newer platform (for example, copying PPC2003 settings to PPC5.0 project), but definitely causes headache is the new project is for an older platform (for example, copying PPC5.0 settings to PPC2003 project).

A Side Topic: The THUMB instruction set consists of 16-bit instructions that act as a compact shorthand for a subset of the 32-bit instructions of the standard ARM. The binary built for THUMB is typically with the size roughly 70-80% that of ARM. Unfortunately binary compiled for THUMB cannot be executed in Windows Mobile 2003 devices.

/etc/hosts file equivalent in Windows Mobile device

2006-04-28T00:11:00.000-07:00

/etc/hosts file equivalent in Windows Mobile device

As you know, the "hosts" file in Windows and other operating systems is used to associate host names with IP addresses. When TCP/IP networking stack tries to resolve a host name to its IP address, it first consults the local hosts file to see whether such mapping is already available. If not, domain name (DNS) server is then consulted. For example, all machines' hosts file might contain the following line:

127.0.0.1 localhost

It maps "localhost" to the loopback address. There is no magic; the TCP/IP stack won't treat "localhost" differently from "www.mit.edu" when it tries to resolve the string name. (For curious mind, the difference comes when IP stack realizes that the IP's first number is 127, a special number.)

Why hosts-like functionality is needed for Windows Mobile device?

Windows Mobile devices does not have the concept of HOSTS file. DNS or WINS is always used. However, a hosts-file-like capability might be useful in certain cases. Below I listed a few possible cases:

Corporate intranet: In a corporate intranet environment, quite possibly a large number of Windows Mobile devices are used. Unlike desktop PCs or Linux/Solaris servers, handheld device does not have a good way for naming, thus typically give IT department more management overhead. Distributed a common hosts file to all Windows Mobile devices is one way to manage.
Some special APIs: A typical example is MSMQ for Windows Mobile devices. In MSMQ, a message queue can be referenced by its path name in the form of "MachineName\QueueName". So able to resolve machine name is essential for MSMQ application to work.
Home or Home Office: At your home you may have a wireless router, several PCs and Windows Mobile devices, all having static-assigned IPs or DHCP-ed IPs. And, you need to sync a device with a home PC over wireless. The trouble is that ActiveSync in the device side needs the name of the desktop PC where ActiveSync is also running, and there is no way for the device to resolve the desktop PC's name (unless you really want to run a WINS service in one desktop PC and configure your device to use the WINS service for name resolution.)

How to make "hosts" in Windows Mobile devices for name resolution?

Although there is no hosts file in Pocket PC or Smartphone's file-system, registry is the place to put such name-IP mappings. To achieve this, add a subkey to HKEY_LOCAL_MACHINE\Comm\Tcpip\Hosts for each machine name that must be resolved, then add binary values for the IP address (value name "ipaddr") and expiration time (value name "expiretime"). The following shows the export of a key entry that resolves the name "hello" to IP address 161.163.165.169. Expiretime is a huge number, indicating no expiration. For the sole purpose of name resolution, expiretime is not strictly needed.

[HKEY_LOCAL_MACHINE\Comm\Tcpip\Hosts\hello]
"ipaddr"=hex:a1,a3,a5,a9
"ExpireTime"=hex:99,99,99,99,99,99,99

Below are the screen shots how to manually add the entry using Remote Registry Editor.

Below is the screen cut shows testing name resolution in the device. The following simple code is used:

C++:
HOSTENT* pHostent = gethostbyname(pchHostName)
or C#:
System.Net.Dns.Resolve(hostName)

Wrap Up

If you only need to take care of one or two name-IP mappings, manually adding them to the registry is do-able. For large number of names, Pocket Hosts is an ideal free utility for such task.

People with good eyesight might notice a subkey called "ppp_peer" in one of screen shots.

[HKEY_LOCAL_MACHINE\Comm\Tcpip\Hosts\ppp_peer]
"aliases"=hex(7):     00
"ipaddr"=hex:     c0,a8,37,64

"ppp_peer" is the name the device gives to the desktop PC during ActiveSync. It maps to IP "c0,a8,37,64" ("192.168.55.100"). In the device side itself, the IP is "192.168.55.101".

Update on the Wrap Up

In Windows Mobile 5.0 devices, ActiveSync in the device gives desktop PC a new name: "dtpt_peer", which maps to IP "A9,FE,02,02" (169.254.2.2). In the device side itself, the IP is "169.254.2.1".

Looks like in Windows Mobile 5.0 emulators (and Windows Mobile 2003 devices), "ppp_peer" is still used.

A little bit on why "ppp_peer" or "dtpt_peer" is needed for ActiveSync: When a windows mobile device plus in a desktop PC, a new network interface is created in the desktop PC. This NIC is named like "Windows Mobile-based Device #n", and its IP is hard coded to be "169.254.2.2". New entries are also added to the PC's routing table, so as to route IP packets destined to 169.254.2.X to only the Window Mobile device.

You may notice when your device is cradled, a small tray icon like networking icon, with a plus sign turning left and right, trying to acquire a network address. You can also try typing "ipconfig /all" and "route print" in a command prompt to play with the this NIC.

As far as I know, you cannot explicitly bind to this specific NIC (disclaimer: Never tried myself.)

Pocket Outlook Woe 02: Domain name is truncated to the same size as password after calling IMailSyncCallBack :: RequestCredentials

2006-04-26T23:38:00.000-07:00

Pocket Outlook Woe 02: Domain name is truncated to the same size as password after calling IMailSyncCallBack::RequestCredentials

In "Pocket Outlook Woe 01", I talked about one issue regarding the latest version of Pocket Outlook (installed with Windows Mobile 5.0 devices, and newer version of Pocket PC 2003 SE devices), that Pocket Outlook passes two NULL pointers as incoming mail server and outgoing mail server to a customized Transport. Today I am focusing on the second woe: domain name is truncated to the same size as that of password after IMailSyncCallBack::RequestCredentials is returned.

IMailSyncCallback: Pocket Outlook itself

The method involved here is called IMailSyncCallBack::RequestCredentials. IMailSyncCallback can be understood as Outlook itself, which provides Transport with methods to interact with Outlook. For example, Transport can:

request memory in tmail.exe's address space
request Outlook to synchronize an account
request Outlook to display a message box

The method giving headache here is RequestCredentials, which is used by Transport to request new credentials from the user.

HRESULT RequestCredentials ( LPCWSTR pszProfile, SYNCCREDENTIALS * ppcredsSource, SYNCCREDENTIALS ** ppcreds );

This is a blocking call. Once called, Outlook shows a dialog to the user asking username, password and domain name. Results won't be returned to Transport until after the user clicks "OK" or "Cancel" in the dialog.

Domain name is truncated!

This simple API works greatly in previous version of Pocket Outlook. However, in the newer version, domain name is always truncated to the same size as that of password. Below are some screen cuts with illustrations:

Screen 1: RequestCredentials() is called. Domain name is "aa.com" (6 characters), password is "12345"

Screen 2: RequestCredentials() returns with a new credential (in parameter ppcreds). Notice domain name is truncated to "aa.co".

Screen 3: RequestCredentials() is called again. Now parameter ppcreds is copied to ppcredsSource.

Screen 4: Let us revert the domain name back to "aa.com", but type "123" as the password.

Screen 5: RequestCredentials() returns with another new credential. Now the domain name is truncated to "aa."

Source code used

The source code is adapted from TransportDemo, really seemingly simple and innocent code.

HRESULT CTransportSyncHandler::Connect(
   DWORD dwReserved,
   SYNCCREDENTIALS* pCredentials
)
{
   HRESULT                            hr                               =      S_OK;
   SYNCCREDENTIALS *      pCurrentCreds      =      pCredentials;
   ULONG                                 cTries                      =      0;

   // The transport is no longer shut down
   ASSERT(m_hEventShutdown != NULL);
   m_fShutDown = FALSE;
   ResetEvent(m_hEventShutdown);

   //while(TRUE)
   while(cTries <= 4) {
       // Do we need to prompt for account info?
       if(cTries || *pCurrentCreds->pszPassword == L'\0') {
            SYNCCREDENTIALS * pNewCreds = NULL;

            // Make a request to the Inbox for logon credentials.
            hr = m_pCallback->RequestCredentials(m_pszProfile, pCurrentCreds, &pNewCreds);
            if(FAILED(hr)) {
                // Log an error...
                if (!m_fShutDown) {
                     LogErrorEvent(CEMAPI_E_NO_ACCOUNT_INFO, 0);
                }
                break;
            }

            // pNewCreds now contains the new info from the user.
            ASSERT(pNewCreds != NULL);

            // Check to see if 'pCurrentCreds' is *not* the ones passed in.
            // If they are not, then we need to free them.    This will happen
            // if the user has been asked more than once for the password.
            if(pCurrentCreds != pCredentials) {
                m_pCallback->FreeMem(pCurrentCreds);
            }

            // what is the new credential
            {
                TCHAR szInfo[1024];
                swprintf(szInfo, TEXT("After RequestCredentials>>\nUserName: %s\nPassword: %s\nDomain: %s"), pNewCreds->pszUsername, pNewCreds->pszPassword, pNewCreds->pszDomain);
                ALERT(szInfo);
            }

            pCurrentCreds = pNewCreds;
       }

       // Now try to connect to the mail server
       // [ Omitted ]
       hr = E_ACCESSDENIED;

       // [ Assumed to return hr ]
       if(FAILED(hr)) {
            if (!m_fShutDown) {
                LogErrorEvent(hr, 0);
            }

            //break;
            // retry instead
       }

       if(m_fShutDown) {
            hr = E_FAIL;
            break;
       }

       // Log in to the mail server
       SetStatusText(0/*IDS_TRANSPORT_CONNECTING*/);          // TODO:    Use an appropriate string resource
       // [ Omitted ]
       // [ Assumed to return hr ]

       // If the logon succeeded, we're done
       if(SUCCEEDED(hr)) {
            break;
       }

       // If we failed due to anything but authentication errors,
       // log the error and bail out
       if(hr != E_ACCESSDENIED) {
            // Log an error back to the application if user didn't himself ask for shutdown
            if (!m_fShutDown) {
                LogErrorEvent(hr, 0);
            }
            break;
       }

       // No success!    Need to hang up and ask the user for new
       // credentials.
       ++cTries;

                // Disconnect from the mail server
       // [ Omitted ]
       // [ Assumed to return hr ]
   }      // while(TRUE)

   if(FAILED(hr)) {
       // Disconnect from the mail server
       // [ Omitted ]
       // [ Assumed to return hr ]
   }

   return hr;
}

Wrap Up

Similar to Outlook Woe 1, I tried to disable the device security, or sign the transport DLL using a certificate, but the problem persists.

This seems affecting not only Windows Mobile 5.0 device, but also newer version of Pocket PC 2003 SE device, where the newer version of Outlook is shipped. The old version of Pocket Outlook actually does NOT show domain-name input box in the credential request dialog.

As a workaround, the user might be required to have a password with the size not shorter than the domain name. For example, "microsoft.com" employee must have a password with at least 13 characters. This sounds like a ridiculous requirement. So again the burden lies on the shoulder of transport developers, who might remember the "original" domain name in a place, and ignore the one passed by IMailSyncCallback. Hereby "original" domain name refers to the one passed by IMailSyncCallback the first time RequestCredentials() is called. Alternatively, registry can be used to store the domain information, rather than relying on Outlook. However, this means that the user cannot change the domain settings via Outlook.

Also similar to Outlook Woe 1, the POP3 transport and IMAP4 transport shipped along with Pocket Outlook seem immune to the issue. Could it because the TransportDemo code is not doing the correct thing in its Connect() method?

Emulator Troubleshooting/Tip 02: Emulator Connecting to Internet (Internet Pass-through Connectivity) Issue

2006-04-24T22:18:00.000-07:00

Emulator Troubleshooting/Tip 02: Emulator Connecting to Internet (Internet Pass-through Connectivity) Issue

The post "Emulator Troubleshooting/Tip 01: To Cradle or Not to Cradle?" is mainly regarding basic knowledge of the new Emulators. Essentially DMA channel is used by Visual Studio and Remote Tools to communicate with the Emulator. It is really NOT that necessary to always ActiveSync an emulator.

Internet Pass-through Connectivity

However, in a lot of cases, the emulator needs to be cradled and ActiveSync'ed. One common requirement is that the emulator wants to use host PC's networking capability, as if it were its own. You can use this feature to perform tasks such as downloading POP3 or IMAP4 email messages, to connect directly with a remote server, or to browse the Internet. This feature is called "Internet Pass-Through". My post briefly talks about how to make it. An excellent post from a Microsoft employee shows much detailed steps with screen cuts.

However, the Microsoft post and a lot of other similar articles only mention what to do in the emulator side. I want to emphasize here that you also need to take care of the ActiveSync side. ActiveSync needs to be instructed whether the host computer is connected to "Work Network" or "The Internet". See below for a screen cut and how to do it:

Click Connection Settings.
Select Open ActiveSync when my device connects.
In the This computer is connected to list, select a connection to which this computer should connected when passing through ActiveSync.

If you are not sure what network to use, choose "Automatic". Hopefully ActiveSync can automatically find out which network the host PC is connected and adjust emulator's setting accordingly.

My Use Case

I am not the lucky one that ActiveSync magically finds out the network to use. It took me 30 minutes to figure out why all of a sudden the emulator in my home PC could not browse internet. Basically the ActiveSync setting is somewhat mysteriously changed to either "Work Network" or "The Internet". Here is my story:

I am using Comcast cable for internet access at home. Occasionally, when I work from home, I run a VPN software in my home PC to place it into the company's intranet. Once in the intranet, any external web site can only be accessed via a proxy server.

Therefore, the emulator in my home PC needs to have internet access in two distinct cases:

My home PC is inside the corporate intranet. In the emulator side, a proxy server must be configured. In ActiveSync side, "Work Network" or "Automatic" must be used. The emulator cannot browse internet if "The Internet" is chosen in ActiveSync.
After business hour, my home PC is directly connected to the public internet. In the emulator side, no special action needs to be taken. In ActiveSync side, "The Internet" or "Automatic" must be chosen. Again, the emulator won't connect if "Work Network" is chosen in ActiveSync.

Wrap Up

Next time when you fight with your emulator that cannot browse a public site, not only check whether the emulator is cradled and ActiveSync'ed successfully, but also check whether ActiveSync side is setup properly!

Pocket Outlook Woe 01: incoming server and outgoing server are passed as two NULL pointers from Outlook to Transport

2006-04-23T00:34:00.000-07:00

Pocket Outlook Woe 01: incoming server and outgoing server are passed as two NULL pointers from Outlook to Transport

I've briefly mentioned how to write a transport plugin for Pocket Outlook in two of my previous posts:

In Pocket Outlook, each mail account is associated with a MAPI store, and a transport. A store is a store, for storing email folders and email messages. The transport is responsible for synchronizing a mail account by talking to the remote server. The main reference on CEMAPI can be found in MSDN's Windows Mobile SDK Messaging section, and the main interface a transport must implement is called IMailSyncHandler.

In Windows Mobile 5.0 devices (and some newer version of Pocket PC 2003 SE devices), a newer version of Pocket Outlook is shipped. This updated version seems bringing a couple of woes to transport developers. Today I am focusing on the first one: Incoming server and outgoing server are passed by Outlook as two NULL pointers to the transport.

The method involved is Install, which is called by Outlook to install the transport and then passes the configuration information to the transport.

HRESULT Install ( LPCWSTR pszProfileName, LPCWSTR pszIncomingServer, LPCWSTR pszOutgoingServer, GUID * pidNetwork );

pszProfileName: [in] Profile name of the transport instance, which is also the account name.
pszIncomingServer: [in] Incoming server name that the transport should use to synchronize the e-mail into the device.
pszOutgoingServer: [in] Outgoing server name that the transport should use to send outgoing e-mails.

Incoming server and outgoing server can be either specified by the user who create the account via Outlook's New Account Setup wizard, or created by the developer using DMProcessConfigXML and EMAIL2 CSP.

I tested both cases, and found that two NULL pointers are always passed from Outlook to the transport. The testing transport is the TransportDemo sample in Windows Mobile SDK. In its Install method, a dialog is used to display two server strings passed by Outlook

Case 1: TransportDemo1 is created by the user using Outlook's wizard

In New Account Setup Wizard, typing the incoming mail server name and outgoing mail server name.

When the transport (TransportDemo) is loaded, two NULL pointers are passed from Outlook.

Case 2: TransportDemo2 is programmatically created using DMProcessConfigXML

The account information can be queried back successfully, showing the two server names correctly. Refer here for how to programmatically query mail account information in Windows Mobile devices, for example, incoming server and username.

Unfortunately, you'll still get two NULL pointers.

Wrap Up

I tried to disable the device security, or sign the transport DLL using a certificate, but the problem persists.

This seems affecting not only Windows Mobile 5.0 device, but also newer version of Pocket PC 2003 SE device, where the newer version of Outlook is shipped.

As a workaround, the transport developer might use registry to store the sever information, rather than relying on Outlook. However, this means that the user cannot change the server settings via Outlook.

The POP3 transport and IMAP4 transport shipped along with Pocket Outlook seem immune to the issue. Could it because the TransportDemo code is too simple and not implement necessary methods??

Emulator Troubleshooting/Tip 01: To Cradle or Not to Cradle?

2006-04-21T00:30:00.000-07:00

Emulator Troubleshooting/Tip 01: To Cradle or Not to Cradle?

Firstly, a quick introduction to the emulators shipped with Visual Studio 2005 (VS2005, and/or Windows Mobile 5.0 SDK).

What is New in the emulators shipped with VS2005

The 2005 emulator runs applications compiled for the ARM instruction set (same as the physical device) and runs as a user-mode process. The emulators work much faster than the previous generations that deal with X86 instruction sets. Also the emulator loading and shutdown time reduce significantly.

The other big change is that VS2005 now provides a Direct Memory Access (DMA) transport to communicate with the emulator. Surpassing the traditional TCP/IP transport, the DMA transport is faster, does not rely on network connectivity or other external factors, and provides deterministic connection and disconnection.

Connect and Cradle Emulator

The centralized place to interact with the emulators is the Device Emulator Manager. To launch the Device Emulator using the Device Emulator Manager in VS2005:

On the Visual Studio Tools menu, click Device Emulator Manager.
In the Device Emulator Manager window, right-click the emulator you want to launch.
On the shortcut menu, click Connect.

The following screen cut show that Pocket PC 2003 SE Emulator is connected. Now VS2005 is able to deploy your program to the emulator and debug your program as well. The Remote Tools (like remote registry editor, remote spy, remote file explorer, and etc) can also work with the emulator. No, in such case, you do not need to establish an ActiveSync connection to use the remote tools.

Sometimes you may need to ActiveSync with an emulator, for example, you want to use the "Mobile Device" shell namespace in your desktop PC's explorer to access the emulator's file system, or you want to make the emulator use the host PC's network connection. The way to establish an ActiveSync connection changed significantly compared to the the previous development environment (Visual Studio 2003/VS2003, Embedded Visual C++ 4/EVC4, and Pocket PC 2003 SDK or Smartphone 2003 SDK).

Right click the already-connected emulator, then click Cradle in the popup menu.
Make sure ActiveSync is configured to allow DMA connections via its Connection Setting dialog's "Allow connections to one of the following" option.
ActiveSync should then start as the emulator makes a connection to your desktop computer.

The following screen cut shows that the Pocket PC 2003 SE emulator is ActiveSync'ed.

To Cradle or Not to Cradle

If an emulator is successfully cradled, VS2005 and Remote Tools can either treat the emulator as an Emulator, or as a Physical Device. For example, in above screen cuts, Pocket PC 2003 SE Emulator is ActiveSync'ed. Now in VS2005 or in Remote Tool's "Select a Windows CE Device" dialog, you can either choose the Emulator as is, or choose "Pocket PC 2003 Device". Either way, the emulator will be connected.

However, you'll see certain degree of performance penalty if the emulator is cradled, compared to a non-cradled emulator. As mentioned above, VS2005 and Remote Tools do not really need the emulator to be ActiveSync'ed. In case that the emulator is not cradled, DMA transport is used. As the named implies, VS2005 or Remote Tool is directly accessing the emulator process' memory, much faster and reliable. Using ActiveSync as the transport adds an unnecessary extra layer.

The other advantage to realize no-need-to-cradle-clarification is that you can connect a Remote Tool to multiple Emulators simultaneously. ActiveSync actually does not support connecting to multiple devices or emulators.

Wrap Up

"To Cradle or Not to Cradle" only applies to Emulators. For a physical device, you do need to cradle and ActiveSync it for VS2005 and Remote Tools to work. Reason is simple. There is no such thing like "DMA" in such a scenario, because the desktop PC and the pocket PC are living in two worlds.

Internal Use Spy: A nice hidden debugging tool for Pocket PC 2003 device and Pocket PC 5.0 device

2006-04-19T22:16:00.000-07:00

Internal Use Spy: A nice hidden debugging tool for Pocket PC 2003 device and Pocket PC 5.0 device

On Apr. 13, 2006, I talked about the usage of Remote CE Spy and how to overcome the broken Remote CE Spy shipped with Visual Studio 2005. Specifically, the Remote Spy displays a list of the windows that are open on a target device. In a separate window, the tool displays information about the messages in the message queue for the selected window.

Remote CE Spy is a very powerful tool for any UI-related programming job. However, the tool requires the target device must be ActiveSync'ed with the desktop PC. What if you do not have access to a PC? With only the physical device, can you discover similar information on the fly, like the window handle, class, style, size, and etc?

Recently when I was playing with my PPC6601 (2003 SE) device, I found such a hidden tool called "Internal Use Spy". The way to bring it up is like this:

Press (and Hold) the Action key
Tap the top title bar where nothing is displayed (to the right of title string, and to the left of notification icon)

A dialog will popup, listing the current window's handle, style, title, client area position and size. Further, it shows the handle of the parent window, and offers a choice to further dump the properties of the parent window. The following screen cut is for "Microphone AGC" applet in the Control Panel Settings:

Wrap Up

I tested in my PPC6700 device, a Windows Mobile 5.0 device. It also works. It seems both Pocket PC 2003 device and Pocket PC 5.0 device have the hidden tool built-in.

The emulator does not expose the same. In the emulator, supposedly one can press and hold the PC's CTRL key to simulate the behavior of pressing and holding Action key in real devices. However, the Internal Use Spy dialog simply does not show up.

For a related post on the hidden trick without connecting the device to a desktop PC, read "how to launch a program via command line in Pocket PC 2003 device and Pocket PC 5.0 device".

Using Camera API with only Embedded Visual C++ 4.0 (evc4): Sample code and EVC4 workspace download

2006-04-17T18:34:00.000-07:00

Using Camera API with only Embedded Visual C++ 4.0 (evc4): Sample code and EVC4 workspace download

In my previous post, I talked about how to use the new Camera API in Windows Mobile 5.0 SDK with only Embedded Visual C++ 4.0 (evc4).

You can download the EVC4 workspace here. The source code is written based on the MSDN documentation on SHCameraCapture, which states:

Application writers should be aware that SHCameraCapture function can cause the calling application to stop responding in cases where the calling application is minimized and then reactivated while the call to SHCameraCapture function is still blocking.

The sample code is written by copying the snippets in that MSDN documentation, although I do not really find such "stop responding" mischief using the "possible sequence of events". The program shows "Capture" and "Exit" in the bottom menu bar. Clicking the left soft key launches the camera capture dialog. After clicking the Action key, the program captures videos for 15 seconds then ask for a place to save the video file.

Two gotchas:

The MSDN documentation says the window class of camera capture dialog is "Camera View". In my Sprint PPC6700 device, the class name is actually "WCE_IA_Camera_Main" (read the source code for a comment).
The camera capture dialog still shows even after the program is closed. The function "CloseCameraDialog" is used to close it before the program shuts down (read the source code for details)

BTW, the tool to find out the window class is Remote CE Spy. The default Remote CE Spy shipped with VS2005 does not work well with Windows Mobile 5.0 device. Read "Remote CE Spy shipped with Visual Studio 2005 fails to intercept windows messages" for a possible solution.

How to use the new Camera API in Windows Mobile 5.0 SDK with only Embedded Visual C++ 4.0 (evc4)?

2006-04-16T23:45:00.000-07:00

How to use the new Camera API in Windows Mobile 5.0 SDK with only Embedded Visual C++ 4.0 (evc4)?

Almost all up-to-date phones, PDAs, or handheld gadgets have an embedded camera, allow users to snap pictures or capture videos. Microsoft releases new APIs in Windows Mobile 5.0 SDK to help developers controlling the camera.

Camera Capture API
Camera enabled devices are extremely popular. With these devices being so widely available, application developers now have the opportunity to substantially enhance the user experience by integrating the capture of both still and video images directly into their applications. To enable application developers to easily provide this functionality, Windows Mobile 5.0 provides the camera capture dialog. The unmanaged API is called SHCameraCapture.

The problem is that the only Visual Studio 2005 can work with Windows Mobile 5.0 SDK. What if you are still using the free Embedded Visual C++ 4 (EVC4), and you do not want to shed a cool $800 to get a copy of VS2005?

The solution is to use LoadLibrary to load aygshell.dll, get the entry point to SHCameraCapture, then call that function by jumping to the entry point. The API anticipates a structure as the parameter, so you need to instruct EVC4 compiler to generate the parameter correctly by defining it yourself. Luckily all the members in the structure are primitive types or character arrays, so there is really not much hassle.

Below is the source code that you can copy and paste into your EVC4 source code. It uses #ifdef _WIN32_WCE to make sure the code gets compiled for Pocket PC 2003 project or Smartphone 2003 project. The final executable can then be copied to a Pocket PC 5.0 device or Smartphone 5.0 device.

#include <aygshell.h>
#if _WIN32_WCE < 0x0500

//////////////////////////////////////////////////////////////////////////////
//
// Flags for camera capture UI

typedef enum {
   CAMERACAPTURE_MODE_STILL = 0,
   CAMERACAPTURE_MODE_VIDEOONLY,
   CAMERACAPTURE_MODE_VIDEOWITHAUDIO,
} CAMERACAPTURE_MODE;

typedef enum {
   CAMERACAPTURE_STILLQUALITY_DEFAULT = 0,
   CAMERACAPTURE_STILLQUALITY_LOW,
   CAMERACAPTURE_STILLQUALITY_NORMAL,
   CAMERACAPTURE_STILLQUALITY_HIGH,
} CAMERACAPTURE_STILLQUALITY;

typedef enum {
   CAMERACAPTURE_VIDEOTYPE_ALL = 0xFFFF,
   CAMERACAPTURE_VIDEOTYPE_STANDARD = 1,
   CAMERACAPTURE_VIDEOTYPE_MESSAGING = 2,
} CAMERACAPTURE_VIDEOTYPES;

typedef struct tagSHCAMERACAPTURE
{
   DWORD   cbSize;
   HWND   hwndOwner;
   TCHAR   szFile[MAX_PATH];
   LPCTSTR   pszInitialDir;
   LPCTSTR   pszDefaultFileName;
   LPCTSTR   pszTitle;
   CAMERACAPTURE_STILLQUALITY   StillQuality;
   CAMERACAPTURE_VIDEOTYPES   VideoTypes;
   DWORD   nResolutionWidth;
   DWORD   nResolutionHeight;
   DWORD   nVideoTimeLimit;
   CAMERACAPTURE_MODE   Mode;
} SHCAMERACAPTURE, *PSHCAMERACAPTURE;

HRESULT SHCameraCapture(PSHCAMERACAPTURE pshcc);

typedef HRESULT (*fnSHCameraCapture)(PSHCAMERACAPTURE pshcc);

HRESULT SHCameraCapture(PSHCAMERACAPTURE pshcc)
{
   HRESULT hr = S_OK;
   HINSTANCE hAygShell = LoadLibrary(TEXT("aygshell.dll"));
   fnSHCameraCapture funcSHCameraCapture = NULL;

   if (!hAygShell) {
   hr = HRESULT_FROM_WIN32(GetLastError());
   goto FuncExit;
   }
   funcSHCameraCapture = (fnSHCameraCapture)GetProcAddress(hAygShell, TEXT("SHCameraCapture"));
   if (!funcSHCameraCapture) {
   hr = HRESULT_FROM_WIN32(GetLastError());
   goto FuncExit;
   }

   // call the API now
   hr = funcSHCameraCapture(pshcc);

FuncExit:
   if (hAygShell) {
   FreeLibrary(hAygShell);
   }
   return hr;
}

#endif   // faked one in 4.20/4.21 platform

Wrap Up

You may use similar approach to access other new 5.0 APIs from within EVC4. You need to find out which DLL exports the API, and more importantly, you need to let EVC4 compiler correctly generate parameters to feed into those APIs, so inevitably you have to copy some header definitions from Windows Mobile 5.0 SDKs.

Remote CE Spy shipped with Visual Studio 2005 fails to intercept windows messages: Check the solution here!

2006-04-13T23:42:00.000-07:00

Remote CE Spy shipped with Visual Studio 2005 fails to intercept windows messages: Check the solution here!

Remote CE Spy is Windows Mobile programmer's buddy if there is a need to inspect the windows currently opened in a Windows Mobile device, or intercept the messages sent to a particular window in real-time. It might not be useful if you are writing simple UI and know for sure what messages to process. However, if you need to find out what is going on with a program written by other people, need to inject messages into the message queue of a program (or to be technically right, a window), or want to find the ID of a window control, Remote CE Spy is an indispensable tool.

CE Spy shipped with Embedded Visual Tools 4 (along with Pocket PC 2003 SDK and Smartphone 2003 SDK) works perfectly, always able to list all the windows, and reliably capture the messages of any window's message queue. However, the one shipped with Visual Studio 2005 is broken. It might list all the windows, but sometimes it doesn't. Worse, when capturing messages sent to a particular window, it grossly misses messages.

Quite some users reported various issues and Microsoft acknowledged it:

Basically those posts are saying that CE Spy is broken in Visual Studio Beta 2. I also found it out when I was using Beta 2. The real trouble is that I am using the RTM version of Visual Studio 2005 (8.0.50727.42, see below). CE Spy still missed capturing messages.

I did a search on my hard drive, and found three version of cespy under "\Program Files". Looks like one of them can work with Windows Mobile 5.0 device.

Version 5.0.1.1400 works!

The following one works without any issue:

C:\Program Files\Common Files\Microsoft Shared\Windows CE Tools\Platman\bin\wce500\cespy.exe

The catch is: After 5.0 device is ActiveSync'ed, this tool won't list Pocket PC 5.0 as a target platform. Just simply choose Pocket PC 2003, the tool can make the connection, list windows and intercept messages correctly!

Version 5.0.1.1400

The window below shows the messages capture by ceSpy.exe 5.0.1.1400 when I clicked the "Send/Receive" menu item of Pocket Outlook. It reports 12 messages. Keep reading on, and you'll be surprised how many messages the "broken" spy is reporting.

Version 5.1.1651.0 (shipped with Visual Studio 2005 RTM and appearing under the start menu "Visual Studio Remote Tools => Remote Spy" does not work

Version 5.1.1651.0 seems to be the on shipped with Visual Studio 2005 and is put under start menu "Visual Studio Remote Tools => Remote Spy":

C:\Program Files\CE Remote Tools\5.01\bin\ccspy.exe (Notice the name is called ccspy.exe, not cespy.exe)

It has no problem connecting to 5.0 device, but messages are grossly missing. Do not use it!

The window below shows the messages capture by ccSpy.exe when I clicked the "Send/Receive" menu item of Pocket Outlook. Only two messages are captured. Compared to the messages intercepted by the good version 5.0.1.1400. This guy fails to report 10 messages!

Version 4.10.1.908 (shipped with Embedded Visual Tools) does not work with 5.0 device, but is the ideal choice to work with 2003 device

The one installed with Embedded Visual Tools does not work against Windows Mobile 5.0 device:

C:\Program Files\Common Files\Microsoft Shared\Windows CE Tools\Platman\bin

This is anticipated, as it is supposed to work with Pocket PC 2003 device and Smartphone 2003 device.

If you ActiveSync'ed a device and try connect, you will get the following error message.

Wrap Up

When you need to use Remote CE Spy to watch windows or messages in a Pocket PC 5.0 device or Smartphone 5.0 device, do not use the one put into the start menu by Visual Studio 2005. Instead, search your hard drive, and locate the one with version 5.0.1.1400.

Please do not ask me why if you cannot find the good guy in your hard drive. I have no idea why I have two different 5.0 versions of them.

How to launch a program via command line in Pocket PC 2003 device and Pocket PC 5.0 device?

2006-04-11T18:55:00.000-07:00

How to launch a program via command line in Pocket PC 2003 device and Pocket PC 5.0 device?

As you may have already known, Pocket PC does not have a shell (unless you want to install one), so there is no easy way to launch a program by typing in command line. Daily average user may not have such requirement. A developer, especially a Java developer, may consider it a nice-to-have feature. Java program is normally launched in the following format:

<jvm_executable> [jvm_argument|jvm_argument] <main_class_name> [program_argument|program_argument]

The command line is usually long. Worse, for debugging purpose, you may need to feed different arguments into your program.

If the device is connected to desktop PC via ActiveSync

If you have setup your development environment and connect the device to your desktop via ActiveSync, the IDE will take care the steps to remote launch a program.

You can also install Windows Mobile Developer Power Toys, which packages a few useful tools for developers:

Emulator ActiveSync Connection Tool - Allows Activesync to connect to your Emulator session from Visual Studio .NET 2003.
ActiveSync Remote Display - Display Pocket PC applications on your desktop or laptop without needing any device side configuration.
CECopy - Command line tool for copying files to the device currently connected to desktop ActiveSync.
Convert PPC DAT to SP XML - Command line tool for generating Smartphone CABWizSP XML docs from existing Pocket PC CAB files.
Hopper - User input stress simulator.
JShell - UI version of the Platform Builder Target Control Window.
PPC Command Shell - Command shell for the Pocket PC 2003 device.
RAPI Debug - Displays detailed information about currently running processes.
RAPI Start - Command line tool to remotely start an application on your Pocket PC from your desktop.
TypeIt - Send characters/strings to the Smartphone 2003 Emulator via ActiveSync.

Among them, RAPIStart and PPC Command Shell can be used for remotely launching an application via command line.

What if the device is not connected to desktop PC, for example, I am outside my office

The above tools requires the Pocket PC to be connected to a desktop PC via ActiveSync. What if you do not have access to a PC? You can try the following:

Go to Today screen (the home screen)
Press (and Hold) the Action key
Tap the position where the current time is displayed in the title bar

A menu pops up with two items: Run and Clock. Click Run, you will get a dialog asking for the program name and arguments.

It is for sure a painful experience to type a long command line in the Pocket PC. You can first write down the command line in a Word Mobile file, then do a copy and paste into the Run dialog. For varying arguments, just do copy and paste then make minor modifications.

In the emulator you can achieve the same, but you need to press and hold your PC's CTRL key to simulate the behvaior of pressing and holding Action key in real devices. See Emulator Keyboard Shortcuts for details.

Pocket PC Power Management Series 10: A Better Way to Catch when the Device Wakes Up - Multi-Thread Code with Visual Studio 2005 Solution Download

2006-04-09T23:46:00.000-07:00

Pocket PC Power Management Series 10: A Better Way to Catch when the Device Wakes Up - Multi-Thread Code with Visual Studio 2005 Solution Download

In Pocket PC Power Management Series 4: A Better Way to Catch when the Device Wakes Up, I present a nice way to catch when the device wakes up. The sample code use CeSetUserNotificationEx to register a named event; when Windows CE OS wakes up, OS fires the event. The code has only one thread, calling MsgWaitForMultipleObjectsEx to both listen to the wakeup event, and process windows message queue. As warned at the end of that post, the single thread might be busy thus missing wakeup events.

Some readers mailed me wondering whether I can provide a fully-functional sample code with two threads such that wakeup event can be always reliably caught. A reader also left a comment asking for the two-thread code. Here I am :)

The VS2005 solution is a Zip file. Extracting it you'll get .sln, .vcproj and source code. Project settings cover Pocket PC 2003 platform and Pocket PC 5.0 platform. For PPC2003 platform, secchk.lib and ccrtrtti.lib are added.

The executable can be run on both Pocket PC 2003 device and Pocket PC 5.0 device. You can use your Pocket IE to download the executable file directly into your device, then run it there.

This is a screen cut when the program runs. All windows messages posted to the main windows (along with the timestamp) are logged to the screen. Besides, any wakeup event (along with the timestamp when the event is fired) are also logged to the screen.

Below is a quick walkthrough of the source code:

The thread that is dedicated to listening to the wakeup signal. Notice it calls WaitForMultipleObjects to actually listen to two events, the other one being the shutdown signal. This also demonstrates how to gracefully shutdown a thread without relying on a global boolean that the thread periodically polling against.

static DWORD WakeupEventListener(LPVOID lpData)
{
  TCHAR szBuf[256];
  PEVENTHANDLES pEventHandles = (PEVENTHANDLES)lpData;

  while (TRUE) {
     ResetEvent(pEventHandles->hWakeupEvent);
     DWORD dwResult = WaitForMultipleObjects(2, (HANDLE*)pEventHandles, FALSE, INFINITE);
     if (WAIT_OBJECT_0 == dwResult) {
        _tcscpy(szBuf, TEXT("Wakeup at "));
        FormatCurrentTime(szBuf+_tcslen(szBuf));
        _tcscat(szBuf, TEXT("\r\n\r\n"));
        OutputString(szBuf);
     } else if (WAIT_OBJECT_0+1 == dwResult) {
        break;
     } else {
        // WAIT_ABANDONED and WAIT_FAILED
        // Abondoned is not possible, failed most probably means the Handle is closed
        if (WAIT_FAILED == dwResult) {
           // ... do something error processing
        }
     }
  }

  return S_OK;
}

Start and stop the wakeup event listener thread.

static HRESULT StartWakeupEventListener(const PEVENTHANDLES pEventHandles, HANDLE& hThread)
{
  DWORD dwDummy = 0;
  hThread = CreateThread(NULL, 0, WakeupEventListener, (LPVOID)pEventHandles, 0, &dwDummy);
  // need to error handling if thread creation failed

  return S_OK;
}

static HRESULT StopWakeupEventListener(const PEVENTHANDLES pEventHandles, HANDLE& hThread)
{
  DWORD dwMilliSec = 2000;
  if (hThread) {
     PulseEvent(pEventHandles->hThreadStop);
     DWORD dwResult = WaitForSingleObject(hThread, dwMilliSec);
     if (WAIT_OBJECT_0 != dwResult) {
        // error or timeout. terminate the thread anyway
        TerminateThread(hThread, -1);
     }

     CloseHandle(hThread);
     hThread = NULL;
  }

  return S_OK;
}

Main logic during program starts up:

to create the wakeup event
to create shutdown signal
to start the wakeup event listener thread

and before the program quits:

to stop the wakeup event listener thread,
to destroy the wakeup event
to destroy the shutdown signal

{
  HRESULT hr = ClearWakeupNotification(g_szEventName);
  hr = AddWakeupNotification(g_szEventName);
  HANDLE hWakeupEvent = CreateEvent(NULL, TRUE, FALSE, g_szEventName);
  HANDLE hThreadStopEvent = CreateEvent(NULL, TRUE, FALSE, TEXT("ThreadStop"));
  EVENTHANDLES eventHandles = {hWakeupEvent, hThreadStopEvent};
  HANDLE hWakeupEventListenerThread = NULL;
  hr = StartWakeupEventListener(&eventHandles, hWakeupEventListenerThread);

  // ..........

  hr = StopWakeupEventListener(&eventHandles, hWakeupEventListenerThread);
  // thread handle already closed
  hr = ClearWakeupNotification(g_szEventName);
  CloseHandle(hWakeupEvent);
  CloseHandle(hThreadStopEvent);
}

Category: [Power Management]

Extreme Makeover - How to rescue a Pocket PC with partially-damaged display screen

2006-04-06T00:27:00.000-07:00

Extreme Makeover - How to rescue a Pocket PC with partially-damaged display screen

Pocket PC is a fragile device. Display screen is Achilles' heel, susceptible to scratches. Worse, if the device is dropped on the floor or ground, the screen may be partially damaged (or completely broken, if that day is really not your day). My officemate actually successfully destroyed the screen of an iPAQ 4155 device.

Besides the obvious choice of trashing the device, or sending it for repair, can we somewhat DIY and still make use of it? I actually do not have the chance myself, but being able to help an unlucky guy who posted a question in a newsgroup:

My touchscreen is a little damaged. After an accidental hard reset it is not possible to go successfully the adjust routine through. I can't start windows mobile (2003). Is there a possibility to start windows and avoid the adjust procedure?

His screen was not completely broken, but he could not use the device, because there was no way he could pass the "screen align" procedure after a hard-reset. My first thought was like: If he could not pass the procedure, why not forcibly kill it? The calibration data is stored under a predefine registry key, then he could manually populate the registry himself.

What tools?

The tools are not hard to find, just remote process viewer and remote regeditor, which are shipped along with Microsoft Embedded Tools (free) or Visual Studio (common). The catch is ActiveSync must be up and running for the remote tools to be able to connect to the device. This should not the a problem, as the ActiveSync components should be more close to OS than the calibration process.

What registry key?

The registry key is not publicly documented, and I do not think either Microsoft or OEMs have any reason to document it. So the correct way to locate the registry key is to find another device with the same model, do a search, then copy the values and names. In my Sprint PPC6601 device, the key is HKLM\HARDWARE\DEVICEMAP\TOUCH, and value name is
CalibrationData, with value data "507,497 150,763 153,230 886,241 871,767".

The guy followed my suggestion, managed to kill the calibration program and populated the registry key. He also contributed another interesting value under that key:

"MaxCalError"=dword:50 - for less sensibility and it works.

Which process to kill?

The final question is how to know which process is showing the "screen align" window. You can guess from the processes listed by remote process viewer. A more rational approach needs another remote tool: the remote spy, which shows all windows in the device. You can easily locate the "screen align" window from the windows captured by remote spy, find which process ID owns the window, then switch to remote process viwer to locate the process.

Read the whole story here.

Wrap Up

There must be a way for Shell to decide not to show the touch screen calibration window upon rebooting. Most probably such information is stored under a predefined registry key. If so, there is really no need to kill the "align screen" window. Instead, using remote regeditor to populate some values is sufficient to rescue your device.

Windows Mobile 5.0 New MAPI Functions Linker Error LNK2019 / LNK2001

2006-04-03T00:33:00.000-07:00

Windows Mobile 5.0 New MAPI Functions Linker Error LNK2019 / LNK2001

In Windows Mobile 5.0, a few new MAPI functions are exposed, namely:

MailComposeMessage
MailDisplayMessage
MailSwitchToAccount
MailSwitchToFolder
MailSyncMessages

If you have worked on MAPI, you may notice these functions are not really that much MAPI related. They are more like Outlook oriented, to facilitate developers to better control Outlooks' UI and built in forms. For example, MailComposeMessage brings up the form to compose an outgoing message, and MailDisplayMessage brings up the form to view a message. I guess the reason that Microsoft exposes these APIs is to help developers make use of Outlook in a very high level, not in the low level of MAPI coding.

I do like the two functions: MailSwitchToAccount and MailSyncMessages, as I need them for my customized transport. However, as soon as I add them to my code, I get a very puzzling linker error:

error LNK2019: unresolved external symbol "long __cdecl MailSwitchToAccount(wchar_t const *,unsigned long)" (?MailSwitchToAccount@@YAJPB_WK@Z) referenced in function _Sync

The lib file "cemapi.lib" is already added to the project's Additional Dependencies, otherwise other MAPI-related code won't even link. So the only reason is because mangled function name generated by the compiler does not match the one in the lib.

The function is declared as:

HRESULT MailSwitchToAccount( LPCTSTR pszAccount, DWORD dwFlags );

I decided to trace down to the root, so I did a "dumpbin /exports cemapi.lib" to see what name and signature should the compiler generate to appease the linker:

?MailSwitchToAccount@@YAJPBGK@Z (long __cdecl MailSwitchToAccount(unsigned short const *,unsigned long))

Aha! Do you, the reader, find the difference? Yes the mangled function names do not match, which is why the linker is not happy. But pay closer attention to the first parameter. In the source code, it is declared as LCPTSTR. My compiler compiles it to "wchar_t const *", but the compiler building the cemapi.lib makes it to "unsigned short const *"!

So here involves a change: Treat wchar_t as built-in type. VS2005 compiler changed the behavior how wchar_t is handled. The previous versions treats wchar_t as unsgined short (via Macro include), but the new compiler in VS2005 treats wchar_t as a built-in type, which is, of course, just wchar_t itself.

Apparently the people who built cemapi.lib turned the option off, which IMHO, was not a wise thing to do, as these APIs will be shipped as part of Windows Mobile 5.0 SDK, and will be used only in Visual Studio 2005 environment anyway.

To fix the issue is easy:

Open the project's Property Pages dialog box.
Click the C/C++ folder.
Click the Language property page.
Modify the Treat wchar_t as Built-in Type property.

There is also a very good blog post from Microsoft employees on the problem. The author summarized a few cases you may encounter such linker error:

You have created a new C++ MFC smart device project and changed the Project -> Properties -> C/C++ -> Language -> "Treat wchar_t as built in type" to "No (/Zc:wchar_t-)"
You have migrated an eVC project to visual Studio 2005, which links to some dependent ATL/MFC DLLs which are compiled using previous versions (like eVC3.0, eVC 4.0 or Visual Studio 2003).
You have migrated you eVC ATL/MFC project to Visual Studio 2005 that has no dependent DLLs, but the Project -> Properties -> C/C++ -> Language -> "Treat wchar_t as built in type" is set to "No (/Zc:wchar_t-)"

My case is exactly the second case, as I've migrated all my projects from Embedded Visual C++ 4 to Visual Studio 2005. Read my migration lessons here...

And at the end, he said "Microsoft are looking at fixing this issue". I certainly hope so!

Category: [Outlook / Transport / MAPI]

Windows Mobile Secure Socket Implementation Series 4: Changes in Windows Mobile 5.0 platform

2006-03-31T00:03:00.000-08:00

Windows Mobile Secure Socket Implementation Series 4: Changes in Windows Mobile 5.0 platform

In previous three posts on Windows Mobile secure socket implementation, I talked about:

In this post I will list the changes of secure socket implementation from Windows Mobile 2003 devices (based on Windows CE 4.2 .NET) to Windows Mobile 5.0 devices (based on Windows CE 5.0 device).

Newly added: remote host name verification

In 5.0 platform, Microsoft adds a new control code SO_SSL_SET_PEERNAME. With such control code, the remote host name is verified by Winsock against the server certificate after a successful SSL handshake. The verification results are then indicated in the certificate validation callback function via the dwFlags parameter. If the specified host name does not match the one indicated in the certificate chain of the SSL Handshake, SSL_CERT_FLAG_ISSUER_UNKNOWN is set in the dwFlags parameter.

It is simple to use the control code:

char* pchHostName = "www.example.com"; // passing somewhere
sockerror = WSAIoctl(in_socket, SO_SSL_SET_PEERNAME,
pchHostName, strlen(pchHostName)+1, NULL, 0, NULL, NULL, NULL);

Notice you need to use strlen(hostname)+1 as the input buffer length (to include the NULL terminator).

If you go through all my previous three posts, you will immediately find that my code actually is doing the same thing in the certificate validation callback function, but I need SslCrackCertificate to crack the BLOB into a X.509 structure. I think the reason why Microsoft adds this new control code is because SslCrackCertificate and SslFreeCertificate are not publicly documented.

My own test reveals that SO_SSL_SET_PEERNAME does not recognize wildcard certificate. Microsoft code possibly just did a literal match between the desired host name and the CN from the subject, like what I did in my sample code.

Warning: If you need to support wildcard certificate, do not use SO_SSL_SET_PEERNAME.

More subtle changes during SSL handshake phase

My experiences dealing with Windows Mobile users tells me: A lot of users forgot to set up their devices' time after a hard-reset. It is not a big deal for smartphones, as the phone can synchronize the time via air. For Pocket PCs, the time is reset to the factory-default one. For example, in my Sprint PPC6600 device (Windows Mobile 2003 SE), the time is reset to some day in 2004.

Why the time matters to secure socket programming? Remember we need to validate the lifetime of a server certificate. If the certificate is already expired, there is no reason we should trust the server, but we may present a dialog to the user, and let the user to decide whether to connect or not. However, in the case of a hard-reset device, the certificate's starting time actually is later than the device's current time. Take PPC6600 device as an example, the current time returned by GetLocalTime() is year 2004, but the server certificate is valid from year 2005 to year 2006. What gives?

You may simply ignore the "post-dated" certificate and continue to establish a secure connection. Better, as a programmer with good sense, you may present a dialog reminding the user to set up the time correctly. The above logic is natural to implement in Windows Mobile 2003 platform; in which, the server certificate is passed into the validation callback function as "normal" by Winsock, so you have the chance to test the lifetime of the certificate.

However, the behavior changed in 5.0 plaform. If the current time of the device is earlier than the starting time of the certificate, dwFlags now contains SSL_CERT_FLAG_ISSUER_UNKNOWN, . IMHO this is a very misleading flag. Now the programmer has no idea whether the server certificate is really a bad one, or the certificate is good but the device's time is bad.

Wrap-Up

You do not really need to change source code in 5.0 platforms, if you do not plan to use the newly added SO_SSL_SET_PEERNAME feature. And, you should not use it at all, if wildcard certificate needs to be supported.

In 5.0 platforms, you lose the capability to gracefully handle a device which has a bad time setting.

Category: [SSL / Socket / Networking / Connection Manager]

Windows Mobile Secure Socket Implementation Series 3: X.509 Certificate and Wildcard Certificate

2006-03-28T23:48:00.000-08:00

Windows Mobile Secure Socket Implementation Series 3: X.509 Certificate and Wildcard Certificate

In previous two posts on Windows Mobile secure socket implementation, I talked about general ideas, and the source code to prepare a socket for secure connection, to crack a BLOB into a X.509 Certificate, and the callback to validate a X.509 certificate.

More on X.509 Certificate, Subject and CN (Common Name)

The function parsing a subject name to retrieve the CN, ParseCN(), is intentionally left out in the source code in previous post. What is a subject, what is CN, and why do we care the subject and CN when we need to validate a certificate?

To answer the above questions, some basic knowledge of X.509 certificate is required. Below are two good and quick readings:

Subject can be roughly understood as the name of an entity, who can be identified by the certificate. CN refers to common name, and in the internet, most probably a host name. Below is Amazon.com's server certificate. Notice the subject line and CN.

CN = www.amazon.com, O = Amazon.com Inc., L = Seattle, ST = Washington, C = US

Now we can answer the question why we need to care subject and CN, because we need to compare CN to the remote host name, to see whether they match. Below is the function to extract CN from the subject line:

char* ParseCN(char* pchSubjLine)
{
   char* pchCommonName = NULL;
   char* pchEnd = NULL;

   if (!pchSubjLine) return NULL;

   pchSubjLine = _strlwr(pchSubjLine);
   pchCommonName = strstr(pchSubjLine, "cn=");
   if (!pchCommonName) {
      return NULL;
   }

   pchCommonName += 3;
   pchEnd = pchCommonName;
   // find the next separator: , or \t or space, or apos
   while ('\0' != *pchEnd && ',' != *pchEnd && ' ' != *pchEnd
      && '\t' != *pchEnd && '\'' != *pchEnd) {
      pchEnd++;
   }
   if ('\0' != pchEnd) pchEnd = '\0';

   return pchCommonName;
}

Wildcard Certificate

If you go back to the source code in my previous post, you may notice that I did a literal match between CN and the remote host name by simply using _stricmp(). This simple literal match should work for most sites, but recently there is an industry trend to use a wildcard certificate, and literal match won't work against such certificate.

What is a wildcard certificate? Let us say a company "example.com" wants to expose 10 web servers to the public internet, all supporting HTTPS:

https://www.example.com
https://www01.example.com
...
https://www09.example.com

The company can buy 10 certificates from CA , each using the fully qualified host name as the CN. Alternatively, the company can buy ONE certificate from CA, using "*.example.com" as the CN. The price of a wildcard certificate is definitely higher than a "normal" certificate, but if the company has a lot of web servers, wildcard certificate can save big. A little bit more information regarding wildcard certificate can be found in "Publishing Multiple Web Sites using a Wildcard Certificate in ISA Server 2004".

Modern browsers like Firefox and IE have no difficulty supporting wildcard certificate and do not complain. Interestingly enough, I found that Pocket IE in both Windows Mobile 2003 devices and Windows Mobile 5.0 devices complains that a wildcard certificate is not a good match to the remote host.

Back to our code. We need to modify the simple literal match to a slightly more advanced one:

if ('*' == *pchCN && '.' == *(pchCN+1)) {
   while ('\0' != *pchRemoteHost && '.' != *pchRemoteHost)
      pchRemoteHost++;
   if ('.' == *pchRemoteHost) {
      bMatched = !(_stricmp(pchRemoteHost+1, pchCN+2));
   }
   // if there is no dot, bMatch remains FALSE
} else {
   bMatched = !(_stricmp(pchRemoteHost, pchCN));
}

Category: [SSL / Socket / Networking / Connection Manager]

Windows Mobile Secure Socket Implementation Series 2: Sample Source Code

2006-03-25T16:46:00.000-08:00

Windows Mobile Secure Socket Implementation Series 2: Sample Source Code

In previous post, I talked about general ideas to write secure socket applications in Windows Mobile device (or actually on Windows CE platforms). The current post has the source code and simple explanations on the code.

Function: Establish a secure socket connection to a remote host:port

Notice the remote host name is passed as certificate validation function's pvArg, which will be given back to us by Winsock when the validation function is called.

int SecureConnect(int in_socket,
   const struct sockaddr * in_pHostInetAddr,
   int in_port )
{
   struct sockaddr_in theInetAddr;
   int sockerror = 0;

   /* initialize the address structures */
   memset (&theInetAddr, 0, sizeof(theInetAddr));

   theInetAddr.sin_family = AF_INET;
   theInetAddr.sin_addr.s_addr = htonl(INADDR_ANY);
   theInetAddr.sin_port = htons(in_port);

   // make it secure
   {
      DWORD dwOptVal = SO_SEC_SSL;
      DWORD dwBytes = 0;
      SSLVALIDATECERTHOOK sslValidateFunc;

      sockerror = setsockopt(in_socket, SOL_SOCKET,
         SO_SECURE, (LPSTR)&dwOptVal, sizeof(dwOptVal));

      if (SOCKET_ERROR == sockerror){
         // error logging
         return 0;
      }

      // register certificate validation callback
      sslValidateFunc.HookFunc = certificateValidationCallback;
      sslValidateFunc.pvArg = "www.sample.com"; // ... passing server name from your context

      sockerror = WSAIoctl(in_socket, SO_SSL_SET_VALIDATE_CERT_HOOK,
         &sslValidateFunc, sizeof(sslValidateFunc), NULL, 0, &dwBytes, NULL, NULL);

      if (SOCKET_ERROR == sockerror){
         // error logging
         return 0;
      }
   }

   // connect
   sockerror = connect(in_socket,
      (struct sockaddr *)in_pHostInetAddr, sizeof (*in_pHostInetAddr));
   if (sockerror == SOCKET_ERROR) {
      // error logging
      return 0;
   }

   {
      // show SSLCONNECTIONINFO
      SSLCONNECTIONINFO SSLConnectionInfo;
      DWORD dwBytes = 0;
      sockerror = WSAIoctl(in_socket, SO_SSL_GET_CONNECTION_INFO,
         NULL, 0, &SSLConnectionInfo, sizeof(SSLConnectionInfo), &dwBytes, NULL,NULL);
      if (sockerror == SOCKET_ERROR) {
         // error logging
         return 0;
      }
      ShowConnectionInfo(&SSLConnectionInfo);
   }

   return 1;
}

Function: Load the functions from schannel.dll, to crack a BLOB into X.509 certificate

The two functions pointers are defined as global variables so that they do not need to be dynamically loaded or unloaded during each SSL handshake phase.

#include <wincrypt.h>
#include <schnlsp.h>

// load SslCrackCertificate and SslFreeCertificate
#define SSL_CRACK_CERTIFICATE_NAME TEXT("SslCrackCertificate")
#define SSL_FREE_CERTIFICATE_NAME TEXT("SslFreeCertificate")

HRESULT LoadSSL()
{
   // already loaded?
   if (gSslCrackCertificate && gSslFreeCertificate) return S_OK;

   hSchannelDLL = LoadLibrary(TEXT("schannel.dll"));
   if (!hSchannelDLL) {
      // error logging
      return E_FAIL;
   }

   gSslCrackCertificate = (SSL_CRACK_CERTIFICATE_FN)GetProcAddress(hSchannelDLL, SSL_CRACK_CERTIFICATE_NAME);
   gSslFreeCertificate = (SSL_FREE_CERTIFICATE_FN)GetProcAddress(hSchannelDLL, SSL_FREE_CERTIFICATE_NAME);

   if (!gSslCrackCertificate || !gSslFreeCertificate) {
      // error logging
      gSslCrackCertificate = NULL;
      gSslFreeCertificate = NULL;
      FreeLibrary(hSchannelDLL);
      hSchannelDLL = NULL;
      return E_FAIL;
   } else {
      return S_OK;
   }
}

HRESULT FreeSSL()
{
   if (hSchannelDLL) {
      FreeLibrary(hSchannelDLL);
      hSchannelDLL = NULL;
   }
   return S_OK;
}

Function: Show SSL connection information for debugging or learning purpose

Do not put it into your release build.

void ShowConnectionInfo(SSLCONNECTIONINFO *pConnectionInfo)
{
   TCHAR szTemp[1028];
   memset(szTemp, 0, 1028*sizeof(TCHAR));

   switch(pConnectionInfo->dwProtocol)
   {
   case SSL_PROTOCOL_SSL3:
   swprintf(szTemp+wcslen(szTemp), TEXT("Protocol: SSL3"));
   break;

   case SSL_PROTOCOL_PCT1:
   swprintf(szTemp+wcslen(szTemp), TEXT("Protocol: PCT"));
   break;

   case SSL_PROTOCOL_SSL2:
   swprintf(szTemp+wcslen(szTemp), TEXT("Protocol: SSL2"));
   break;

   default:
   swprintf(szTemp+wcslen(szTemp), TEXT("Protocol: 0x%08x"), pConnectionInfo->dwProtocol);
   }
   wcscat(szTemp, TEXT("\n"));

   switch(pConnectionInfo->aiCipher)
   {
   case CALG_RC4:
   swprintf(szTemp+wcslen(szTemp), TEXT("Cipher: RC4"));
   break;

   case CALG_3DES:
   swprintf(szTemp+wcslen(szTemp), TEXT("Cipher: Triple DES"));
   break;

   case CALG_RC2:
   swprintf(szTemp+wcslen(szTemp), TEXT("Cipher: RC2"));
   break;

   case CALG_DES:
   swprintf(szTemp+wcslen(szTemp), TEXT("Cipher: DES"));
   break;

   case CALG_SKIPJACK:
   swprintf(szTemp+wcslen(szTemp), TEXT("Cipher: Skipjack"));
   break;

   default:
   swprintf(szTemp+wcslen(szTemp), szTemp, TEXT("Cipher: 0x%08x"), pConnectionInfo->aiCipher);
   }
   wcscat(szTemp, TEXT("\n"));

   swprintf(szTemp+wcslen(szTemp), TEXT("Cipher strength: %d"), pConnectionInfo->dwCipherStrength);
   wcscat(szTemp, TEXT("\n"));

   switch(pConnectionInfo->aiHash)
   {
   case CALG_MD5:
   swprintf(szTemp+wcslen(szTemp), TEXT("Hash: MD5"));
   break;

   case CALG_SHA:
   swprintf(szTemp+wcslen(szTemp), TEXT("Hash: SHA"));
   break;

   default:
   swprintf(szTemp+wcslen(szTemp), szTemp, TEXT("Hash: 0x%08x"), pConnectionInfo->aiHash);
   }
   wcscat(szTemp, TEXT("\n"));

   swprintf(szTemp+wcslen(szTemp), TEXT("Hash strength: %d"), pConnectionInfo->dwHashStrength);
   wcscat(szTemp, TEXT("\n"));

   switch(pConnectionInfo->aiExch)
   {
   case CALG_RSA_KEYX:
   case CALG_RSA_SIGN:
   swprintf(szTemp+wcslen(szTemp), TEXT("Key exchange: RSA"));
   break;

   case CALG_KEA_KEYX:
   swprintf(szTemp+wcslen(szTemp), TEXT("Key exchange: KEA"));
   break;

   default:
   swprintf(szTemp+wcslen(szTemp), TEXT("Key exchange: 0x%08x"), pConnectionInfo->aiExch);
   }
   wcscat(szTemp, TEXT("\n"));

   swprintf(szTemp+wcslen(szTemp), TEXT("Key exchange strength: %d"), pConnectionInfo->dwExchStrength);
   MessageBox(NULL, szTemp, NULL, NULL);
}

Function: Certificate validation callback

Notice the order how it checks the certificate and other parameters. Sometimes Winsock passes false alarms in dwFlags. The way how Winsock internally handles the certificate in Windows Mobile 5.0 devices (Windows CE 5.0 based) is also changed from Windows Mobile 2003 devices (CE 4.2 based). This will be discussed in my later post.

// the certificate validattion for SSL
int certificateValidationCallback(
   DWORD dwType,
   LPVOID pvArg,
   DWORD dwChainLen,
   LPBLOB pCertChain,
   DWORD dwFlags)
{
   X509Certificate* pCert = NULL;
   int nRet = SSL_ERR_CERT_UNKNOWN;

   // dwType must be SSL_CERT_X.509
   if (dwType != SSL_CERT_X509) {
      // error logging
      return nRet;
   }

   if (dwFlags & SSL_CERT_FLAG_ISSUER_UNKNOWN) {
      // error logging
      return nRet;
   }

   if (pCertChain == NULL) return nRet;
   ASSERT(dwChainLen == 1);

   if (!gSslCrackCertificate || !gSslFreeCertificate) {
      // error logging
      return nRet; // unable to crack
   }

   // crack X.509 Certificate
   if (!gSslCrackCertificate(pCertChain->pBlobData, pCertChain->cbSize, TRUE, &pCert)) {
      // error logging
      return SSL_ERR_BAD_DATA;
   }

   // Site check
   {
      char* pchSubject = NULL;
      char* pchCN = NULL;
      BOOL bMatched = FALSE;
      char* pchRemoteHost = (char*)pvArg;

      pchSubject = pCert->pszSubject;

      // here you need to parse the subjec to retrieve the CN name
      pchCN = ParseCN(pchSubject);
      if (!pchCN) {
         goto FuncExit;
      }

      // CN comparison
      bMatched = !(_stricmp(pchRemoteHost, pchCN));
      if (!bMatched) {
         // error logging
         goto FuncExit;
      }
   }

   // validFrom, validUntil check
   {
      SYSTEMTIME stNow;
      FILETIME ftNow;
      FILETIME ftValidFrom = pCert->ValidFrom;
      FILETIME ftValidUntil = pCert->ValidUntil;

      GetSystemTime(&stNow);
      SystemTimeToFileTime(&stNow, &ftNow);

      if (!(IsEarlierThan(&ftValidFrom, &ftNow) && IsEarlierThan(&ftNow, &ftValidUntil))) {
         // give user an option to continue or not
         // a little more lenient than Subject check
      }
   }

   nRet = SSL_ERR_OKAY;

FuncExit:
   gSslFreeCertificate(pCert);

   return nRet;
}

Category: [SSL / Socket / Networking / Connection Manager]

Windows Mobile Secure Socket Implementation Series 1: General Idea

2006-03-22T00:24:00.000-08:00

Windows Mobile Secure Socket Implementation Series 1: General Idea

Whenever you need to write socket-based programs, very possibly you need to implement a secure socket. For example, if you develop your own mini-http client, you have to deal with HTTPS; if you write an IMAP4 client, you may need to support STARTTLS command. Or, you are writing both the server in the desktop and the client for Windows Mobile device, and need to support a secure communication channel.

I plan to write four articles on the series of secure socket implementation:

General idea
Sample source code
X.509 Certificate and how to deal with wildcard certificate
Changes in Windows Mobile 5.0 platform (vs. 2003 devices on 4.2 platform)

Different from Windows desktop environment, Windows CE platform exposes a very nice way to write secure socket program. Adding a security infrastructure requires few code changes to "normal non-secure" socket-based applications. Once a secure socket is connected, the application may send and receive data on that socket unaware that the data over the wire is encoded. You can just write the boilerplate socket code and functions: socket(), connect(), read(), recv(), closesocket().

The procedure to establish a secure socket connection is well documented by Microsoft, ever since 3.0:

Below are the two critical steps:

Set the socket in secure mode with the setsockopt function. Set level to SOL_SOCKET, optname to SO_SECURE, and optval to a DWORD set to SO_SEC_SSL.
Specify the certificate validation callback function by calling WSAIoctl with the SO_SSL_SET_VALIDATE_CERT_HOOK control code.

Notice the certificate validation callback function:

int SslValidate (
   DWORD  dwType
   LPVOID pvArg
   DWORD  dwChainLen
   LPBLOB pCertChain
   DWORD  dwFlags
);

Below are explanations of some important parameters:

The dwType parameter specifies the data type pointed to by pCertChain. It must be SSL_CERT_X.509.
The pvArg parameter is the application-defined context. It is a nice place to pass information against which you want to verify, for example, remote host name.
The pCertChain parameter is a pointer to a BLOB struct, which contains a X.509 certificate (ISO standard). The certificate is the server certificate. You can parse the certificate to extract the pertinent data like the subject and life cycle.
dwFlags parameter will contain SSL_CERT_FLAG_ISSUER_UNKNOWN, if the root issuer of the certificate could not be found in the client device's CA database. Notice WinSock sometimes passes false alarms in this parameter.

If you simply return SSL_ERR_OKEY in your certificate validation callback, then any faked or invalid SSL certificate is deemed valid. This obviously defeats the purpose of establishing a trusted secure communication channel. You need to do your due diligence by testing at least three things:

to test the dwFlags passed to you by WinSock,
to test the server certificate to see whether the certificate subject name matches the remote host name,
and, to test whether the server certificate is already expired.

Most probably you do not need to test the issuer, since Winsock already did the job by checking the server certificate against the root CA store in the device.

One tricky business of how to parse the pCertChain Blob to get the following structure:

typedef struct _X509Certificate {
   DWORD           Version;
   DWORD           SerialNumber[4];
   ALG_ID          SignatureAlgorithm;
   FILETIME        ValidFrom;
   FILETIME        ValidUntil;
   PSTR            pszIssuer;
   PSTR            pszSubject;
   PctPublicKey    *pPublicKey;
} X509Certificate, * PX509Certificate;

The way to crack the Blob is not documented by Microsoft, but it it not difficult to find out by searching in major search engines: to use SslCrackCertificate and SslFreeCertificate that are exported from schannel.dll. Once you have the X.509 structure, you can easily validate it against the remote host name (by checking pszSubject), and life cycle (by checking ValidFrom and ValidUtil).

I'll post ready-to-compile source code in my next post.

Category: [SSL / Socket / Networking / Connection Manager]

1.1 .NET Framework is Needed for Smart Device Projects targeting 1.0 NET CF (Compact Framework) in Visual Studio 2005 (VS2005)

2006-03-18T18:45:00.000-08:00

1.1 .NET Framework is Needed for Smart Device Projects targeting 1.0 NET CF (Compact Framework) in Visual Studio 2005 (VS2005)

Our new team member was opening a SDK sample C# solution in Visual Studio 2005, and could not build it. I took a look at the output window. The output was huge with 700+ lines, considering how tiny the sample project is. The following error message was shown there:

C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Microsoft.CSharp.Targets(147,9): error VSD6000: Projects targeting .NET Compact Framework 1.0 require version 1.1 of the .NET Framework, which is not detected on this machine.

This sounds strange and interesting, as I never seen this error message in my own PC. A quick search results in the following MSDN2 library documentation:

Version 1.1 of .NET Framework required

Looks like the team member just installed a fresh PC with VS2005 and Windows Mobile SDKs, and apparently Visual Studio 2005 installed .NET Framework 2.0, but not 1.1. To solve the problem is easy, just downloading .NET Framework 1.1 and installing it in the team member's PC.

I did not see this problem in my own PC, because several versions of .NET Framework already reside in my PC. Such weird requirement actually puzzled me. Why cannot .NET 2.0 Framework do the job, if .NET 1.1 can do? I am not familiar with what happens under the hood, but just wondering how confusing it is. I myself did a lot of java coding (ever since JDK 1.1), and I've never seen such a weird requirement that old JDK or JRE has to be present for some stuff to work. Kudos to Sun Microsystem guys!

Another thing worth mentioning is one statement in that MSDN2 documentation page:

Smartphone 2003 projects fall into this category (.NET Compact Framework version 1.0)

Sometimes I saw people posted questions to certain forums wondering how to develop .NET CF 2.0 applications for Smartphone 2003 platforms. Unfortunately this is not supported. The root reason is that Smartphone 2003 does not persist "\Windows" folder (the one it persists is "\Storage\Windows"). Rather funny, huh? It is not because certain APIs are not available in Smartphone 2003, nor because Smartphone 2003 is "too small"...

The following .NET CF team blog presents an excellent table on what platforms can support .NET CF 2.0:

.NET Compact Framework Version 2 .CAB Files Explained

In short, .NET CF 2.0 is supported on:

Pocket PC 2003 and 2003 SE
Windows Mobile 5.0 PPC
Windows Mobile 5.0 Smartphone

You even cannot find an installation .NETCFv2 CAB package for Smartphone 2003 platform.

Out of curiosity, I checked what .NET CF version are stored out of box for the following devices:

Sprint PPC6700: 1.0.4292.00 (Windows Mobile 5.0 Pocket PC, OS Version 5.1.1700, Build 14352.0.1.0)
Sprint PPC6601: 1.0.3316.00 (Windows Mobile 2003 SE Pocket PC, OS Version 4.21.1088, Build 14132)
I-Mate SP3i: 1.0.3316.00 (Windows Mobile 2003 Smartphone)

Category: [Development Environment]

Source code to find out all the programs that are installed in a Windows Mobile device and that can be un-Installed

2006-03-15T00:08:00.000-08:00

Source code to find out all the programs that are installed in a Windows Mobile device and that can be un-Installed

In the post "Programmatically find out all the programs that can be unInstalled in Windows Mobile devices", I showed how to locate a list of programs installed in a Windows Mobile device. Pocket PC 2003 and other newer platforms (Smartphone 2003, Pocket PC 5.0, and Smartphone 5.0) have to be handled differently.

A reader actually sent me an email for the source code. Oh well this is an easy one so I am posting here:

#include "cfgmgrapi.h"
HRESULT QueryAllInstalled_DM()
{
  LPTSTR szProvXMLOut = NULL;
  TCHAR szProvXMLIn[512];

  memset(szProvXMLIn, 0, 512*sizeof(TCHAR));
  wcscat(szProvXMLIn, TEXT("<wap-provisioningdoc><characteristic-query type=\"UnInstall\">"));
  wcscat(szProvXMLIn, TEXT("</characteristic-query></wap-provisioningdoc>"));

  HRESULT hr = DMProcessConfigXML(szProvXMLIn, CFGFLAG_PROCESS, &szProvXMLOut);
  if (!FAILED(hr)) {
    ALERT2(TEXT("SUCCESS"), TEXT("DM"));
  } else {
    ALERT2(TEXT("FAILED"), TEXT("DM"));
  }
  ALERT2(szProvXMLOut, TEXT("DM"));

  DELETE_STR(szProvXMLOut);

  return hr;
}

#define APPS_REGHOME TEXT("\\Software\\Apps")
static HRESULT QueryAllInstalled_Registry()
{
  HRESULT hr = E_FAIL;
  LRESULT lr = E_FAIL;
  HKEY hKey = NULL;

  DWORD dwcSubKeys = 0; // Number of sub keys
  DWORD dwcMaxSubKeyName = 0; // Longest sub key name
  TCHAR* szSubKeyName = NULL; // subkey names
  DWORD j = 0;

  // Open the predefined registry
  lr = RegOpenKeyEx(HKEY_LOCAL_MACHINE, APPS_REGHOME, 0, 0, &hKey);
  if (ERROR_SUCCESS != lr) {
    goto FuncExit;
  }

  // Get Value count.
  lr = RegQueryInfoKey(hKey, // Key handle.
    NULL, // Buffer for class name.
    NULL, // Length of class string.
    NULL, // Reserved.
    &dwcSubKeys, // Number of sub keys.
    &dwcMaxSubKeyName, // Longest sub key size.
    NULL, // Longest class string.
    NULL, // Number of values for this key.
    NULL, // Longest Value name.
    NULL, // Longest Value data.
    NULL, // Security descriptor.
    NULL); // Last write time.

  // Enumerate the sub keys
  if (!dwcSubKeys || dwcMaxSubKeyName <= 0) {
    goto FuncExit;
  }
  szSubKeyName = new TCHAR[dwcMaxSubKeyName+1];
  if (NULL == szSubKeyName) {
    goto FuncExit;
  }

  for (j = 0, lr = ERROR_SUCCESS; j < dwcSubKeys; j++)
   {
    DWORD dwcSubKeyName = dwcMaxSubKeyName;
    memset(szSubKeyName, 0, sizeof(TCHAR)*(dwcMaxSubKeyName+1));
    HKEY hSubKey = NULL;

    lr = RegEnumKeyEx(
      hKey,
      j,
      szSubKeyName,
      &dwcSubKeyName,
      NULL,
      NULL,
      NULL,
      NULL);

    if (ERROR_SUCCESS != lr) {
      continue;
    }

    // now we have the key name. let us open it.
    lr = RegOpenKeyEx(hKey, szSubKeyName, 0, 0, &hSubKey);
    if (ERROR_SUCCESS != lr) {
      continue;
    }

    DWORD dwInstl = 0;
    DWORD dwValueType = REG_DWORD;
    DWORD dwValueLen = sizeof(DWORD);
    lr = RegQueryValueEx(hSubKey, TEXT("Instl"), NULL, &dwValueType, (LPBYTE)&dwInstl, &dwValueLen);
    if (ERROR_SUCCESS == lr) {
      if (dwInstl == 1) {
        ALERT2(szSubKeyName, TEXT("From Registry"));
      }
    }

    RegCloseKey(hSubKey);
  }

FuncExit:
  if (szSubKeyName) {
    delete []szSubKeyName;
  }
  if (hKey) {
    RegCloseKey(hKey);
  }

  return hr;
}

Category: [Setup / Install / unInstall / Upgrade]

Programmatically find out all the programs that can be unInstalled in Windows Mobile devices

2006-03-12T22:34:00.000-08:00

Programmatically find out all the programs that can be unInstalled in Windows Mobile devices

In my previous post, I talked about how to programmatically unInstall/remove/delete one program in Windows Mobile devices. Notice that is only for one program. In this post, I am going to talk about how to find out all the programs that can be un-installed in a Windows Mobile device. With such a list, we can programmatically un-install all those programs. To enterprise customers, such functionality is a very welcome one, who deem the ability to remote-destroying lost or stolen devices a MUST-Have feature.

Like what I did in the previous post on programmatically unInstall/remove/delete one program in Windows Mobile devices, I have to treat Pocket PC 2003 differently from other newer platforms to locate a list of un-installable programs

Pocket PC 2003 platform

Information about what programs are installed in a Pocket PC 2003 device can be found under registry key "\HKLM\SOFTWARE\Apps\". Each program is listed as a sub-key, with program name as the sub-key name. For each program, the value "CabFile" stores what is the original CAB file (the installation package), and value "InstallDir" is where (in which directory) the program is installed to.

Notice not all the programs listed there can be unInstalled, but only the sub-key with value "Instl" = dword:1. So to find a list of programs that can be uninstalled in a Pocket PC 2003 device, you can simply iterate through all sub-keys under registry hive "\HKLM\SOFTWARE\Apps\" with value "Instl" = dword:1. The APIs to use are RegOpenKeyEx, RegQueryInfoKey, RegQueryValueEx, and mainly RegEnumKeyEx.

Other newer platforms (Smartphone 2003, Pocket PC 5.0, Smartphone 5.0)

As I put in my previous post, Microsoft wants to move anything regarding mobile device management and configuration to its CSP (Configuration Service Provider) architecture. UnInstallation is one CSP. UnInstall Configuration Service Provider not only uninstalls applications from the device, but also returns information like what programs can be unInstalled. Below is the exact XML to feed into DMProcessConfigXML to get the list of un-installable programs in a Smartphone 2003 device, Pocket PC 5.0 device, or Smartphone 5.0 device:

<wap-provisioningdoc>
<characteristic-query type="UnInstall">
</characteristic-query> </wap-provisioningdoc>

Category: [Setup / Install / unInstall / Upgrade]

Programmatically unInstall/remove/delete one program in Windows Mobile devices

2006-03-09T18:49:00.000-08:00

Programmatically unInstall/remove/delete one program in Windows Mobile devices

Sometimes you need to provide functionality to programmatically unInstall/remove/delete a program from a user's device. Let us think about a use case: Your program is managing some private or sensitive data. Unfortunately the user lose the device, or some one stolen the device. Either case, the capability to remotely destroy the program and data is highly desired. If you are targeting enterprise customer, this remote-destroy functionality is almost certain listed as one of MUST-Have features.

How to send a signal to or notify a lost device is the other story that I might talk later in another blog post, here I solely focus on how to programmatically unInstall a program in Windows Mobile devices.

Pocket PC 2003 platform

In Pocket PC 2003 devices, you can simply execute "\Windows\unload.exe" and pass program name as the parameter. I guess you should know your own program's name :)

The program name is the concatenation of "Provider" and "AppName" specified in your .INF file (the file for cabwiz to build)
The program name is listed in the list of "Settings" => "System" => "Remove Programs"

You can call either CreateProcess or ShellExecuteEx to spawn unload.exe. If you want to be a little more prefessional, call WaitForSingleObject on the handle to the new process returned by both calls. Remember to close those handles!

Other newer platforms (Pocket PC 5.0, Smartphone 2003, Smartphone 5.0)

The simple method of running unload.exe does not work in newer Windows Mobile platforms: Smartphone 2003, Pocket PC 5.0, Smartphone 5.0. Microsoft wants to move anything regarding mobile device management and configuration to its CSP (Configuration Service Provider) architecture. UnInstalling program is one CSP. UnInstall Configuration Service Provider uninstalls applications from the device. A provisioning document that contains XML to uninstall an application should contain only that XML and no other provisioning information.

MSDN documentation states that using UnInstall CSP is "the
cleanest way to uninstall an application under the transactioning model for
Windows Mobile Version 5.0 software for Smartphones". Actually it is also the case for Smartphone 2003 device.

Below is a code snippet for such purpose:

   // build an XML for UnInstallation
   // using stack , sloppy code
   TCHAR szProvXML[512];
   LPTSTR szPvXMLOut = NULL;
   memset(szProvXML, 0, 512*sizeof(TCHAR));
   wcscat(szProvXML, TEXT("<wap-provisioningdoc><characteristic type=\"UnInstall\"><characteristic type=\""));
   wcscat(szProvXML, TEXT("TestingApp"));
   wcscat(szProvXML, TEXT("\">"));
   wcscat(szProvXML, TEXT("<parm name=\"uninstall\" value=\"1\"/>"));
   wcscat(szProvXML, TEXT("</characteristic></characteristic></wap-provisioningdoc>"));
   HRESULT hr = DMProcessConfigXML(szProvXML, CFGFLAG_PROCESS, &szPvXMLOut);

Category: [Setup / Install / unInstall / Upgrade]

How to retrieve/get TO, CC, BCC recipient address of an email through CEMAPI (C++) in Windows Mobile device?

2006-03-02T21:01:00.000-08:00

How to retrieve/get TO, CC, BCC recipient address of an email through CEMAPI (C++) in Windows Mobile device?

Whenever you deal with email application through MAPI (or, CEMAPI, the trimmed version in Windows Mobile devices), quite possibly you need to load TO addresses, CC addresses from a given email message (or BCC addresses in case the message is in "draft" folder or "Sent Item" folder) . For example, when developing a mail transport, you not only need to synchronize the account's inbox with the remote server, but also have to deal with outgoing messages. Inevitably, you have to know TO/CC/BCC of any outgoing message.

Intuitive thought is to query them as corresponding properties from the message object IMessage using its GetProps method. Although the CEMAPI documentation is scarce, one can still find such properties from the header files:

PR_DISPLAY_BCC
PR_DISPLAY_CC
PR_DISPLAY_TO

Unfortunately all of three properties returned me empty strings, at least in Pocket PC 2003 devices. Time to take a google search to see whether other people ran into the same issue. I did find two fellow clueless guys, who posted the question but got no useful answers:

So I had to take the more complex approach, using the recipient table. Every message has a recipient table. Each record in the recipient table is a recipient, and has a couple of properties/columns. As with any other MAPI stuff, an email address is a property, a recipient's name is also a property, and an address type (TO/CC/BCC) is also a property.

So I changed my simple code to a slightly longer one:

opening the recipient table by calling GetRecipientTable,
setting the interested properties by calling SetColumns,
iterating through the table record-by-record by calling QueryRows

Heck! This seemingly perfect and innocent code still did not work. After a debug, I soon realized that SetColumns returns a COM error meaning not implemented. Not surprisingly, CEMAPI is not the full-fleged MAPI in the desktop world, and here we tasted a slight bitterness.

So the natural solution is to loop though all the properties for each record, and figure out the type of each property. The number of the properties for each recipient is SRow.cValues, and the type of each property is specified in SPropValue.ulPropTag. Below is a code snippet:

  // the hack is to loop through all rows without limiting the columns
  HRESULT hr = pMessage->GetRecipientTable(0, &pRecipientTable);
  EXIT_ON_FAILED(hr);

  // iterate all the recipients
  while (TRUE) {
    hr = pRecipientTable->QueryRows(1, 0, &pRows);
    if (FAILED(hr) || !pRows || pRows->cRows != 1) break;

    // nProps is the number of columns in the recipient table
    int nProps = pRows->aRow[0].cValues;
    ULONG ulReceipType = 0;

    // loop through all the properties
    for (int ii = 0; ii < nProps; ii++) {

      ULONG ulPT = pRows->aRow[0].lpProps[ii].ulPropTag;

      switch (ulPT) {
      case PR_EMAIL_ADDRESS:
        // This is the email address
        szReceipEmail = pRows->aRow[0].lpProps[ii].Value.LPSZ;
        break;
      case PR_RECIPIENT_TYPE:
        // this is the recipient type: TO/CC/BCC
        ulReceipType = pRows->aRow[0].lpProps[ii].Value.ul;
        break;
      case PR_DISPLAY_NAME:
        // this is the display name
        szReceipName = pRows->aRow[0].lpProps[ii].Value.LPSZ;
        break;
      default:
        break;
      }  // switch
    }
  }

Category: [Outlook / Transport / MAPI]

How to programmatically query mail account information in Windows Mobile devices, for example, incoming server and username?

2006-02-21T00:05:00.000-08:00

How to programmatically query mail account information in Windows Mobile devices, for example, incoming server and username?

Pocket Outlook manages a few mail accounts. Out of box there is an account called "Outlook E-Mail", which is used to synchronize with Desktop Outlook. For Pocket PC Phone edition and Smartphones, out of box there is another account called "Text Messages", which is used to store SMS. Besides, a user can create new accounts using Pocket Outlook's New Account Wizard and manually typing required information, such as incoming server, outgoing server, username, mail transport (POP3 or IMAP4, or customized ones), and the etc.

Developers can programmatically create mail accounts using omnipotent DMProcessConfigXML. The CSP (Configuration Service Provider) to use is EMAIL2. Read the great example in MSDN on how to achieve this purpose.

There is not much to talk about how to create a mail account. What I am trying to tackle here is how to query back the mail account information, for example, trying to enumerate all the mail accounts that a user has setup in Pocket Outlook, and get the authentication and server information. Such information is useful and handy, if you have your own pieces of application that deals with mail accounts, and you want to prevent users from having to manually type all the information in twice (once in the mail setup and once in your application).

For 5.0 devices, Microsoft provides a new managed namespace to deal with Outlook: Microsoft.WindowsMobile.PocketOutlook. EmailAccountCollection class defines the set of all e-mail accounts that are currently configured on the mobile device. However, the class EmailAccount only provides account name and transport name, which is far less than enough for our purpose. Besides, we also need to target Pocket PC 2003 devices, which does not the managed environment yet.

DMProcessConfigXML is the natural way (and seemingly the only way) to go. The trouble is, you need to feed this nice API with a GUID, like the following:

<wap-provisioningdoc>
  <characteristic type="EMAIL2">
    <characteristic-query type="{D671C70B-8EE3-4881-8045-2AEE6F731B55}"/>
  </characteristic>
</wap-provisioningdoc>

What the heck? Why not simply using the human-readable human-memorable account name, which is unique anyway? Well, the guys in Redmond apparently developed a better appetite to consume GUIDs, which can be supplied, indeed, infinitely. Of course, not infinitely in strict mathematical sense. So in addition to CSLID, IID, LIBID, ..., we have another GUID, the ID to identify each mail account.

Now we need to solve the simple problem of digging out the GUID for each account. How about trying the usual hack to search in registry? No! It does not work. No such information is stored in registry.

Do not give up yet. So let us resort to our friend MAPI here. Hate it or love it, the more than 10-year-old MAPI still powers messaging applications in Windows kingdom, under the hood of CDO or later Outlook PIA. With MAPI being so ancient, you can easily smell its unusualness from its way of using complex structures to define properties and make everything a table of records, every record a number of properties.

And a little bit of knowledge how Pocket Outlook's mail account is linked to an MAPI store. Each mail account is associated with a MAPI store, and a transport. A store is a store, for storing email folders and email messages. The transport is responsible for synchronizing a mail account by talking to the remote server. Outlook itself manages UI and coordinates the transport and the store. Enough with the abstract stuff, two concrete samples: "Outlook E-Mail" is associated with a store called "ActiveSync", "Text Messages" is associated with a store called "SMS".

Back to the main topic: What we need to do is to using MAPI to achieve two purposes:

Enumerate all mail accounts
Find GUID for each account

The first purpose is easy to achieve. We just need to enumerate all MAPI stores. The straightforward approach is to open the message store table and iterate through all records; for each record, we load the MAPI store name.

The second purpose is a little harder to fulfill. Digging in "cemapi.h", the main header file for CEMAPI (a trimmed version of MAPI for CE device), one line caught my eye:

// This property is to uniquely identify a store. It's a guid.
#define PR_CE_UNIQUE_STORE_ID PROP_TAG(PT_CLSID, 0x8113)

Aha! Here we are. This must be the GUID we need. See the comment, its name and the type, exactly a GUID. Since this is a property associated with a store, we can query it in two ways:

While iterating through the records in the message store table, we request a column PR_CE_UNICODE_STORE_ID when inspecting each record;
Or, we can load the PR_ENTRY_ID for each MAPI store, and open the store then query the property by calling GetProps.

The first approach saves both coding and runtime computation, so below is the code following first approach.

Notice "ActiveSync" and "SMS" are not inspected by the code. This is anticipated, as they do not have "username" or "incoming server" in the normal sense. Also notice EMAIL2 won't give you the password :)

#include "cfgmgrapi.h"
// Query a mail account information using DMProcessConfigXML API
// IN: the account GUID
HRESULT QueryAccountInfo(LPCTSTR szAccountGUID)
{
   LPTSTR szProvXMLOut = NULL;
   TCHAR szProvXMLIn[512];

   memset(szProvXMLIn, 0, 512*sizeof(TCHAR));
   wcscat(szProvXMLIn, TEXT("<wap-provisioningdoc>
      <characteristic type=\"EMAIL2\"><characteristic-query type=\""));
   wcscat(szProvXMLIn, szAccountGUID);
   wcscat(szProvXMLIn, TEXT("\"/>"));
   wcscat(szProvXMLIn, TEXT("</characteristic></wap-provisioningdoc>"));

   HRESULT hr = DMProcessConfigXML(szProvXMLIn,
      CFGFLAG_PROCESS, &szProvXMLOut);
   if (!FAILED(hr)) {
      //...
   } else {
      // ... do error handling
   }
   ALERT(szProvXMLOut);

   DELETE_STR(szProvXMLOut);

   return hr;
}

// Query all stores
HRESULT QueryMsgStore(IMAPISession* pMAPISession)
{
   HRESULT hr = S_OK;
   IMAPITable* pMsgStoresTable = NULL;
   LPSRowSet pRows = NULL;

   enum {
      ePR_DISPLAY_NAME,
      ePR_CE_UNIQUE_STORE_ID,
      NUM_COLS
   };

   // These tags represent the attachment prop information
   // we would like to pick up
   SizedSPropTagArray(NUM_COLS, Columns) =
   {
      NUM_COLS,
      PR_DISPLAY_NAME,
      PR_CE_UNIQUE_STORE_ID,
   };

   // get the message store table
   hr = pMAPISession->GetMsgStoresTable(0, &pMsgStoresTable);
    EXIT_ON_FAILED(hr);

   // Get the display name and all store IDs
   // for each message store
    hr = pMsgStoresTable->SetColumns((LPSPropTagArray)&Columns, 0);
    EXIT_ON_FAILED(hr);

   // loop through
   while (TRUE) {
      hr = pMsgStoresTable->QueryRows(1, 0, &pRows);
      if (FAILED(hr) || pRows->cRows != 1) {
         if (!FAILED(hr)) hr = E_FAIL;
          EXIT_ON_FAILED(hr);
      };

      if (PR_DISPLAY_NAME ==
         pRows->aRow[0].lpProps[ePR_DISPLAY_NAME].ulPropTag
         &&
         PR_CE_UNIQUE_STORE_ID ==
         pRows->aRow[0].lpProps[ePR_CE_UNIQUE_STORE_ID].ulPropTag) {

         // this is the display name column
         TCHAR *pszStoreName = pRows->aRow[0].lpProps[0].Value.LPSZ;
         ALERT(pszStoreName);

         // Now we got the GUID
         LPGUID pGUID = pRows->aRow[0].
            lpProps[ePR_CE_UNIQUE_STORE_ID].Value.lpguid;

         TCHAR szAccountGUID[40] = {0};
         memset(szAccountGUID, 0, 40*sizeof(TCHAR));
         wsprintf(szAccountGUID,
            TEXT("{%08X-%04X-%04X-%02X%02X-%02X%02X%02X%02X%02X%02X}"),
            pGUID->Data1, pGUID->Data2, pGUID->Data3,
            pGUID->Data4[0], pGUID->Data4[1],
            pGUID->Data4[2], pGUID->Data4[3],
            pGUID->Data4[4], pGUID->Data4[5],
            pGUID->Data4[6], pGUID->Data4[7]);
         QueryAccountInfo(szAccountGUID);
      }

      if (pRows) {
         FreeProws(pRows);
         pRows = NULL;
      }
   }

FuncExit:
   if (pRows) FreeProws(pRows);
   RELEASE_COMOBJ(pMsgStoresTable);

   return hr;
}

Category: [Outlook / Transport / MAPI]

TransportDemo sample in Pocket PC 5.0 SDK does not work? Check the solution here...

2006-02-12T00:09:00.000-08:00

TransportDemo sample in Pocket PC 5.0 SDK does not work? Check the solution here...

I am going to start a new category "Outlook and MAPI related". I have been developing a customized mail transport for Pocket Outlook for quite some time, and have programmed MAPI extensively.

A good start to learn how to write a customized mail transport is to read the TransportDemo sample shipped in both Windows Mobile 2003 SDK and Windows Mobile 5.0 SDK. It gives the reader good heads-up what important methods to implement (IMailSyncHandler), what to export in the transport DLL (OneStopFactory), and how to register the transport in registry. The sample does not really synchronize a mail account, nor does it send outgoing emails. And, the sample does not show how to programmatically provision a new mail account based on the customized transport (a possible new blog post here?); rather, it anticipates the reader to manually create one via Pocket Outlook's New Account Wizard.

With all the above being said, I found that I could not create a new account in Pocket PC 5.0 emulator. I tried both manual creation using Outlook's New Account Wizard, and programmatic way using DMProcessConfigXML. The account simply does not show up. Soon I realized the account WAS created, but was NOT listed in Outlook, based on the following three reasons:

Since I had already worked on a customized transport in Pocket PC 2003 and Smartphone 2003 for quite some time, I was pretty sure that I built the DLL and registered the transport in the registry correctly.
Further, the account must already have been created, as I could not created a second one with the same name.
Further, I could easily query back the account information using DMProcessConfigXML.

A quick google group search reveals three fellow victims:

None of them found the solution. So I was on my own here. Why the account was created but could not be displayed? Could it be caused by the fact that I did not sign the DLL, as Pocket PC 5.0 is most probably a "one-tier-prompt" device (security-related, another big category in my mind)? Soon I dismissed this possibility. I tried two methods to rule out the security concern. First method was to sign the DLL using the SDK privileged certificate ("SDKSamplePrivDeveloper.pfx"), and load the certificate to the emulator (how? a possible new blog post). Second method was to disable security settings in the emulator (how? a possible new blog post). In both cases, the account simply refused to show up.

In despair, I wrote a small program to load my own DLL and call the function "OneStopFactory". Arrrr... LoadLibrary() failed!! Till this point, I knew the reason: Certain DLLs must be missing in the emulator. After running depends.exe (although in my desktop PC, but still emitted some traces), I found that "msvcr80d.dll" is required. So I copied it from my desktop ("C:\Program Files\Microsoft Visual Studio 8\VC\ce\Dll\armv4i") to the Pocket PC 5.0 emulator. Upon restarting Pocket Outlook, all previously-created accounts showed up.

Category: [Outlook / Transport / MAPI]

How to put your own Control Panel Applet to "Personal" Group?

2006-02-03T19:15:00.000-08:00

How to put your own Control Panel Applet to "Personal" Group?

In Pocket PC 2003 and Pocket PC 5.0, there are three groups of Control Panel Applets: "Personal", "System" and "Connection". Looks like if you simply build a CPL file and export "CPlApplet" function, your Applet will be displayed in the "System" group. No exception is mine. However, quite some users and managers along my management chain think that our Control Panel Applet should be put into "Personal" group. I agree. It is used by the user to control his preferred email-reading-and-composing behavior, which apparently, has nothing to do with any system-wide activity. So I was dispatched the task to drop the Applet to "Personal" group.

I failed to find any useful documentation by searching in major searching engines and MSDN documentation, at the time when I was starting to working on it. I do found an unfamiliar CPL_IDNAME message, with the following description in Pocket PC 2003 SDK documentation:

This message is sent to the Control Panel application to retrieve its unique name string. This string can be used to find its data in the registry.

Man, guess no people can understand what the heck is "... to find its data in the registry...". So I decide to take a look at Pocket PC 5.0 SDK documentation, hoping I could find more up-to-date explanation:

The CPL_IDNAME message is sent to the CPlApplet function to retrieve a Control Panel application's unique ID name string.
Handling of this message is required only if the application icon exists in a Settings application tab other than the default System tab. When this message is received, the CPlApplet function must copy the ID name of the application (specified by uAppNum) into the pszName parameter. The ID name can be used to retrieve or set information about the application via the registry subkey [HKEY_LOCAL_MACHINE\ControlPanel\<IDname>]. The primary data under this subkey is "Group" = dword:1. The possible values for the Group data indicate the tab of the Settings application where the application icon exists.

Yes, there we are. So below are what we need to do to list the CPL in "Personal" Group, whose group number is 0. Assume the IDName is called "TestingApp". By the way, this name does not need to be your real application name.

Must-Do 1: Register the ID Name in the specified registry hive. You can put the following code in your setup DLL's Install_Exit function.

    // Set up registry keys
    // [HKEY_LOCAL_MACHINE\ControlPanel\TestingApp\]
    // Groupe=dword:0
    TCHAR szKeyBase[MAX_PATH];
    _tcscpy(szKeyBase, TEXT("\\ControlPanel\\TestingApp"));
    LRESULT lr = Registry_SetDWordValue(HKEY_LOCAL_MACHINE,
              szKeyBase, TEXT("Group"), dwGroup);

Must-Do 2: Respond to CPL_IDNAME in CPlApplet function.
    case CPL_IDNAME:
    {
      UINT uApp = lParam1;
      LPWSTR pszName = (LPTSTR)lParam2;
      _tcscpy(pszName, TEXT("TestingApp"));
      return 0;
    }

Must-Do 3: Remember to remove the registry hive in your un-Install code. You can put such code in your setup DLL's Uninstall_Exit function.

Alternatively, you do not really need to write code for Must-Do 1 and Must-Do 3. In your .INF file for CabWiz, adding the following sections:

    [DefaultInstall]
    CopyFiles      = XXXXX
    AddReg         = Reg.CPLApplet

    [Reg.CPLApplet]
    HKLM,ControlPanel\%AppName%,Group,0x00010001,0
    ; assuming you alrady defined AppName=TesinngApp

That is it! Microsoft Cab installer will take care the steps to add the registry key during installation, and remove the registry key during un-installation.

Below is a screen cut showing "TestingApp" is put into "Personal" group:

Category: [Control Panel]

Pocket PC Power Management Series 9: Battery Life Matters

2006-01-24T00:02:00.000-08:00

Pocket PC Power Management Series 9: Battery Life Matters

In my previous series, I talked about the reasons why Pocket PC's battery life is not that great in general. Part of the reason is the intrinsic design problems that we developers have to live with. This reminds me of what the VP in my company once talked to me regarding the battery life in Symbian devices.

Symbian OS runs in a much larger number of handheld units worldwide. Very possibly you, as the reader, is using a phone powered by Symbian OS. In general, the Symbian phones have considerably longer battery life than Pocket PCs (and smartphones). My VP once had a conversation with Symbian guys how they achieve the goal to save battery. His wonder is understandable, since Symbian OS is also numerous lines of human-made codes, so there is no magic. The answer from Symbian guys is that they have put battery-life as the top priority when the OS was designed. They make the kernel and shell very efficient in terms of CPU usage.

One can argue that Windows CE is much more powerful than Symbian OS, so a little more power-hungry is acceptable. Well, probably the argument is not to the point. Smartphone is also powered by Windows CE OS, but have better battery life than Pocket PC. Again, one can argue that smartphone does not have a touch screen, and its LCD is much smaller than that of Pocket PC, so smartphone's LCD consumes less power than Pocket PC. Well, probably the point is missed again. How do you explain the mysterious "\Software\Microsoft\Shell\LowMem" registry setting in Smartphone (which controls how the Shell killed user application at will)? Looks like in Pocket PC, Microsoft suspends itself and all user applications to save battery. In smartphones, Microsoft changed the strategy. It kills user applications to save battery!

Enough for the debate. Developers have to live with it anyway, and have to code prudently to not unnecessarily burn precious battery. How? Again I strongly recommend you to read the two excellent articles from Mike Calligaro:

Mike generalizes the following principles:

Don't use the CPU unless you really need to
Stop using the CPU as soon as you can
- Stop using the CPU when your app isn't in the foreground.
- Stop using the CPU if the user hasn't interacted with your app for a little while

Also Mike presents a great multi-threaded sample to catch any power state change reported by OS's Power Manager.

Still we may have to develop certain applications that need to run continuously (I called it case-1 programs), or applications that need to run periodically (I called it case-2 programs). See my Series 2 for the problem domain and Series 5 for details of case-1 and case-2. For such programs, Mike's principles still apply, but I'd like to add the following suggestions specific to our problem domain:

Prefer CeSetUserNotificationEx than SystemIdleTimerReset. The latter one I
called it a brutal way to force the device to run, and the former one a gentle way to request the device to run. You may not really need to run the program continuously. "Downgrade" to running periodically if possible.
Offer your user a choice to control the time period and frequency when the program runs. I bet the user will thank you for your extra work in putting a Control Panel Applet there!
Make sure not to turn on the display unnecessarily even when your program has to run unattended. Some options of CeSetUserNotificationEx might turn on the LCD display, but probably only on some models. You need to diligently test the physical device.
The ancient advice holds true: Make your code efficient. Avoid unnecessary loop. Cache your data if making sense. Do not write too computationally-intensive code. The list goes on and on. In general, if you come from Desktop Windows world and probably forget those algorithms taught in data structure classes, now probably is time to pick up again!

Category: [Power Management]

Pocket PC Power Management Series 8: Why Pocket PC's Battery Life so Notorious?

2006-01-12T23:30:00.000-08:00

Pocket PC Power Management Series 8: Why Pocket PC's Battery Life so Notorious?

In my two previous Pocket PC Power Management Series (Series 5 and Series 6), I am trying to tackle the task of writing either continuously-running or periodically-running programs. I must admit such programs do not fit nicely into Microsoft's Windows Mobile-powered Pocket PCs, after having working on such applications myself for more than 1 year. Why? The fundamentally-flawed design of the Pocket PC devices prevent any good developer from developing really battery friendly programs.

When Pocket PC device was initially designed, Microsoft made the decision that the device should never shutdown, probably by following Palm's design. Unless battery is removed, the device is always "alive". Unfortunately, Microsoft's OS is a trimmed version of its bigger brother Desktop Windows. Desktop Windows was never designed to be CPU or power friendly; in fact, desktop Windows seems to be proudly following the path of being more and more power hungry. Windows CE, trimmed down in the sense of fewer APIs, does not have any luxury of touching the underlying OS layer to make it more battery friendly. So I guess Pocket PC team had to make the decision to force the OS to sleep frequently to save power. The basic idea is like: Aha, CPU is running and burning battery. How about I force it not to run?

This idea apparently does not fly, or at least, does not fly well. Why? As Mike Calligaro from Microsoft points out, "Staying on all the time actually burns less power than going to sleep." Why? "The issue is that it takes a 'long' time to go to sleep and a similarly long time to wake back up." Please read his excellent post for details.

To make matter worse, Pocket PC 2003 uses RAM as storage. RAM must be powered constantly to keep its stuff, even if the device is sleeping. This is another big battery sucker. As Mike Calligaro vividly pointed out in his another post, when you see the dire warning saying something to the effect of, "You are running of battery. Batter save your data now, because you're on the verge of losing it." At that point, you can't use the device again until you plug it in. How much battery charge do you think you have then? Try half. Yes, when you are shut down because your batteries were "critically low," they were still 1/4 to 1/2 full. Why? Because, if the batteries ever fully died, it would be catastrophic. You'd lose your data. So Microsoft made a requirement and held OEMs to it. The requirement was that, at the point where the batteries were decided to be "critically low," they had to still have enough power to keep the RAM charged for 72 hours.

Realizing the two fundamental flaws of Pocket PC devices: (1) Forcing CPU not to run to save battery actually consuming more battery; (2) Using RAM as storage just does not work the way out, Microsoft learnt the lesson and designed the smartphone platform quite differently. The smartphone does not sleep, and can be shutdown just like a desktop computer. And, smartphone uses Flash as storage, which consumes much less power. Both smartphone 2003 and smartphone 5.0 are like this.

Unfortunately, Pocket PC 5.0 still inherits the sleeping legacy from Pocket PC 2003, although it uses Flash as storage. That is why all my previous posts apply to both Pocket PC 2003 and Pocket PC 5.0.

Next I will talk about how to make your program battery friendly. This is particularly important, since our problem domain are applications that need to run either continuously or periodically.

Category: [Power Management]

Pocket PC Power Management Series 7: Trap of GetTickCount, and Sleep()

2006-01-08T23:46:00.000-08:00

Pocket PC Power Management Series 7: Trap of GetTickCount, and Sleep()

If you come from desktop Windows world, very possibly you developed a habit to call GetTickCount() to keep track how long has elapsed, for example, to wait for a time interval to pass. Basically the API retrieves the number of milliseconds that have elapsed since the system was started. The elapsed time is stored as a DWORD value. Therefore, the time will wrap around to zero if the system is run continuously for 49.7 days. Although the warning message is printed everywhere in Microsoft documentation and in every tutorial, programmers love to use it, thinking they never need to track a task for as long as 59.7 days :)

What I want to emphasize to the desktop Windows programmers, is that GetTickCount() might fail miserably in Pocket PC devices. When the Pocket PC device is suspended, the internal timer is also suspended, thus stop increasing value. For example, at 10:00AM your program calls GetTickCount() to retrieve a DWORD value (time1), and the device runs unattended for 3 minutes then falls asleep; after another 5 minutes, the device wakes up, and your program resumes execution and calls GetTickCount() again to retrieve another DWORD value (time2). You may anticipate the difference between time2 and time1 equals to 8 minutes. Nope! The difference is actually 3 minutes, and you just missed 5 minutes that was when the device was sleeping.

One solution is to use GetLocalTime() API to retrieve the local time as ULONGLONG, then do arithmetic operation on two ULONGLONG values to calculate the real time elapsed. Notice GetLocalTime() has one headache: You need to take into account whether the end user changed the local time setting or not. To avoid such headache, you call use QueryPerformanceCounter() for similar purpose. Not surprisingly, QueryPerformanceCounter() has its own issue: It cannot sustain device reboot. So you need to make a trade off between these two choice.

Similar to the trap of GetTickCount(), desktop programmers also need to notice that Sleep() API cannot really sleep for the specified time period. Most probably, your thread will sleep longer, sometimes much longer. Please refer to my Pocket PC Power Management Series 3 for details, where I present a program making use of such sleep-longer-expected feature to determine whether the device was suspended or running.

Category: [Power Management]

Pocket PC Power Management Series 6: Request the Device to Run: a Gentle Way

2005-12-20T13:06:00.000-08:00

Pocket PC Power Management Series 6: Request the Device to Run: a Gentle Way

In Pocket PC Power Management Series 5, I showed how to use API SystemIdleTimerReset to force the device not to sleep. However, this technique is an overkill and a waste if used for case-2 programs (which need to run periodically, not continuously). Further, some utilities are known to disrupt SystemIdleTimerReset, for example, Keyguard.

A more gentle way is to request the device to run at certain time, by using the omnipotent CeSetUserNotificationEx (see my Pocket PC Power Management Series 4 for a brief introduction to this API). Hereby I present three ready-to-use functions.

1. How to Use?

If you want to run Pocket IE to browse a URL 10 minutes later, simply call:

ScheduleRunApp(TEXT("\\Windows\\iexplore.exe"), TEXT("URLXXX""), 600);

And remember to clear it after some time:

ClearRunApp(TEXT("\\Windows\\iexplore.exe"));

2. Walkthrough of the functions

SecondsAfter: It takes a pointer to SYSTEMTIME and a number of seconds,;
upon returning, the SYSTEMTIME is modified to be exactly that number of
seconds after the original time. For example, if original time is 10:00AM
now, and you want to a time 10:05AM, just pass 300 as the second parameter.
The function converts SYSTEMTTIME to FILETIME for easy arithmetic operation.

static HRESULT SecondsAfter(SYSTEMTIME* pst, int numSeconds)
{
  FILETIME ft;

  // convert to FILETIME then ULONGLONG for calculation
  if (!SystemTimeToFileTime(pst, &ft)) return E_FAIL;
  ULONGLONG ulLongFt = *(ULONGLONG*)&ft;
  ulLongFt += (ULONGLONG)numSeconds * 10000000;
  // 10000000: how many nano seconds per second, divided by 100

  // convert back to FILETIMEand SYSTEMTIME
  ft = *(FILETIME*)&ulLongFt;
  if (!FileTimeToSystemTime(&ft, pst)) return E_FAIL;
  return S_OK;
}

ScheduleRunApp: It takes an Executable name, arguments and a number of
seconds. All parameters are self-explanatory. For example, if you pass 300
as dwAfterSeconds, the program is scheduled to run 5 minutes after the
function is called.

static HRESULT ScheduleRunApp(
  LPCTSTR szExeName,
  LPCTSTR szArgs,
  DWORD dwAfterSeconds)
{
  HRESULT hr = S_OK;
  HANDLE hNotify = NULL;

  // set a CE_NOTIFICATION_TRIGGER
  CE_NOTIFICATION_TRIGGER notifTrigger;
  memset(&notifTrigger, 0, sizeof(CE_NOTIFICATION_TRIGGER));
  notifTrigger.dwSize = sizeof(CE_NOTIFICATION_TRIGGER);

  // calculate time
  SYSTEMTIME st = {0};
  GetLocalTime(&st);
  hr = SecondsAfter(&st, dwAfterSeconds);
  if (FAILED(hr)) {
    return hr;
  }

  notifTrigger.dwType = CNT_TIME;
  notifTrigger.stStartTime = st;

  // timer: execute an exe at specified time
  notifTrigger.lpszApplication = (LPTSTR)szExeName;
  notifTrigger.lpszArguments = (LPTSTR)szArgs;

  hNotify = CeSetUserNotificationEx(0, &notifTrigger, NULL);
  // NULL because we do not care the action
  if (!hNotify) {
   hr = E_FAIL;
  } else {
   // close the handle as we do not need to use it further
   CloseHandle(hNotify);
  }
  return hr;
}

ClearRunApp: I want to emphasize and repeat what I said in Pocket
PC Power Management Series 4 regarding CeSetUserNotificationEx. One
notorious side-effect of CeSetUserNotificationEx is that the notification
will be persisted in a central repository, unless the creator remembers to
remove it. I've seen a couple of novice developers forgot to clear the
notifications and subject his/her testing device to some really weird
behaviors. So I also present ClearRunApp, which is used to clear previously
scheduled tasks. Remember: Even if the task already ran, the notification is
still persisted, unless cleared programmatically.

static HRESULT ClearRunApp(LPCTSTR szExeName)
{
  HRESULT hr = S_OK;

  // hold a notification
  PBYTE pBuff = (PBYTE)LocalAlloc(LPTR, 8192);

  if (!pBuff) {
    return E_OUTOFMEMORY;
  }

  // at most 256 notification handles
  HANDLE hNotifHandlers[256];
  DWORD nNumHandlers, nNumClearedHandlers = 0;
  DWORD i = 0;
  int rc = CeGetUserNotificationHandles(hNotifHandlers,
  dim(hNotifHandlers), &nNumHandlers);
  if (!rc) {
    hr = E_FAIL;
    goto FuncExit;
  }

  // iterate all notifications
  // Notice: We do not care about the status of the notification.
  // Just clear it even if it is not filed??
  for (; i<nNumHandlers; i++) {
    // query info for this specific handler
    BOOL bClearThis = FALSE;
    DWORD dwSize = 0;
    rc = CeGetUserNotification(
    hNotifHandlers[i], 8192, &dwSize, pBuff);
    if (!rc) continue;

    PCE_NOTIFICATION_INFO_HEADER pnih =
     (PCE_NOTIFICATION_INFO_HEADER)pBuff;
    PCE_NOTIFICATION_TRIGGER pNotifTrigger = pnih->pcent;
    // Notice some events with NULL lpszApplication might be inserted!
    if (pNotifTrigger && pNotifTrigger->lpszApplication
      && !_tcsicmp(pNotifTrigger->lpszApplication, szToCompare)) {
      CeClearUserNotification(pnih->hNotification)
    }
  }


  FuncExit:
  if (pBuff) {
    LocalFree(pBuff);
  }

  return hr;
}

3. Further thoughts

If you do not need the style of "running a program AFTER some time", rather, what you want is "running a program AT certain time", you can simply modify ScheduleRunApp as needed.

Category: [Power Management]

Pocket PC Power Management Series 5: Force the Device not to Sleep: a Brutal Way?

2005-12-05T22:56:00.000-08:00

Pocket PC Power Management Series 5: Force the Device not to Sleep: a Brutal Way?

In Pocket PC Power Management Series 3 and Series 4, I demonstrated two ways to find out when the device is running, and when it is sleeping. The techniques is not much useful, unless you need to take certain actions when the device wakes up. Remember, there is NO WAY for you to take action when the device falls asleep. (You may write a driver, but that is completely out of my scope here.)

Now let us move into the more interesting topic, trying to solve the problem defined in Pocket PC Power Management Series 2. You need to write a media player, able to playing music without being suspended. Or, you need to write a stock alert program, able to monitor a stock symbol from time to time. The first case, case 1, is a continuously-running program, and the second, case 2, a periodically-running program. Apparently you do not want the OS to suspend your nicely running program abruptly, at least for the first case, the media player case.

Microsoft anticipates such need, and exposes an API:

void WINAPI SystemIdleTimerReset(void);

Basically this function resets a system timer that controls whether or not the device will automatically go into a suspended state. Let us say you set the device to power down in 3 minutes on battery power (via "Settings"=>"System"=>"Power"=>"Advanced"=>"Turn off device if not used for 3 minutes"). Each time this function is called, the device will run for another 3 minutes even if not used.

The frequency in which to call SystemIdleTimerReset in order to keep a device awake can be determined by retrieving the following registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Power

Value "BattPowerOff" determines the seconds the device will be suspended on battery power (180 standing for 3 minutes), and value "ExtPowerOff" determines the seconds if on AC power (0 meaning no sleeping on AC).

Notice this API should be used cautiously for the following two reasons:

It should only be used for continuously-running programs (case 1), rather than periodically-running programs (case 2). It is a waste of battery if used for case-2 programs. For case-2 application, the omnipotent CeSetUserNotificationEx should be used (see my Pocket PC Power Management Series 4 for a brief introduction to this API).
Some utilities are known to disturb SystemIdleTimerReset. Keyguard is such one. Basically when your device is locked (unresponsive to any keypresses), Keyguard is placed to prevent you from hitting the device keys accidentally (while it is in your pocket) and prevent the backlight from coming on and drain the battery or making unwanted phone calls. If your program starts from sleep mode and the Keyaguard mode is on, then SystemIdleTimerReset does not work and the device suspend after specific time. Again the solution is to use CeSetUserNotificationEx but in a slightly more creative way.

Because of the nature of SystemIdleTimerReset, I call it a brutal way to force the device not to sleep. In next post, I plan to discuss how to use CeSetUserNotificationEx to more gently "request the device not to sleep", a good solution to case-2 programs, and case-1 programs as well.

Category: [Power Management]

Error: cab file could not be created - No, not again! Nice workaround/solution

2005-11-28T12:42:00.000-08:00

Error: cab file could not be created - No, not again! Ultimate workaround/solution

How many times did you see the dreaded message "Error: CAB file 'XXX.CAB' could not be created", after you managed to tackle the compilation error, managed to build the needed DLLs, EXEs, and managed to write a good CAB .inf file? Worse, the error file that CabWiz is supposed to dump error message is empty! This left you cluelessly scratching your head, having no idea what exactly you did wrong.

I have seen so many such errors in my development, and I do not think I did anything wrong. Why? Here is my story posted to Microsoft MSDN forum. Sometimes the new CabWiz (shipped with VS2005) worked, sometimes did not. Sometimes the old CabWiz (shipped with PPC2003 SDK) worked, sometime did not. Sometimes everything worked in my PC, but not in my teammate's...

With the incredible tool from the wizards in sysinternals, I monitored the file-system activities after launching CabWiz. Looks like CabWiz first analyzed the .INF file, generated an intermediate file based on a template (cabwiz.ddf), then asked makecab.exe to build the CAB based on the intermediate file. Makecab failed at the stage when a CAB was being created, for no apparent reason. That explained why CabWiz could not report any meaningful error message, because makecab.exe did not communicate with CabWiz why it failed.

Finally I figured out probably the buggy tool is not comfortable with the long fully-qualified CAB filename. So I did a subst, making sure the current directory for CabWiz is very short. Viola! It works. So the ultimate solution is to use Subst to shorten the absolute name of your CAB file, and launch CabWiz from that shorten path.

Example:

Original path of INF file

c:\MyWork\WindowsMobile\superlong1\superlogn2\superlong3 superlogn4\superlogn5\superlogn6\superlogn7 MailClient\src\Shared\MailClient_release.PPC2003_en.inf

Do a subst:

Subst v: c:\MyWork\WindowsMobile\superlong1\superlogn2\superlong3 superlogn4\superlogn5\superlogn6\superlogn7

Then file Cabsize in V: rather than in C:

Sometimes even if the original path is not very long (like 120 characters), CabWiz still fails. A subst is still a good solution.

PS: Microsoft's documentation on Subst. Or you can type "subst /h" on the command line to see the details how it works.

Category: [Cabwiz / Build]

How to debug Control Panel Applet in Pocket PC 2003 and Pocket PC 5.0?

2005-11-17T17:31:00.000-08:00

How to debug Control Panel Applet in Pocket PC 2003 and Pocket PC 5.0?

Recently I was enhancing a Control Panel Applet for my Pocket PC application, which was developed in a hurry one year ago, with very rudimentary user interfaces. This time I expanded it to 4 tabs, with more professional UIs.

All went on well, until I hit a problem today: After making some code changes, the Applet no longer shows up after I click it! Not able to find out any issue from the source code, I decided to do a debug. Unfortunately a Control Panel Applet cannot be directly started, because it is essentially a DLL which exports a CPlApplet function. So I have to find a host executable for debugging purpose.

1. Basic knowledge about Pocket PC Control Panel Applet

The way how Control Panel Applet is loaded by the system is well documented. Basically the CPL file must export the following function:

LONG CALLBACK CPlApplet (HWND hwndCPL, UINT uMsg, LONG lParam1, LONG lParam2)

And the CPL must be able to deal with a series of messages sent from Windows, namely:

CPL_GETCOUNT
CPL_INIT
CPL_NEWINQUIRE
CPL_STOP

2. Write my own host executable? Overkill?

So I can easily write a program that

load the CPL ("LoadLibrary")
get the function address of CPlApplet("GetProcAddress"),
and send a series of messages: CPL_INIT, CPL_GETCOUNT, CPL_NEWINQUIRE, CPL_DBLCLK (to show the UI!), CPL_STOP, and CPL_EXIT

I actually find such one, although it does not send CPL_DBLCLK to display the UI.

3. ctlpnl.exe? Nope it does not work!

It looks to me a little overkill to write a program just for the sake of a debugging. So I am wondering whether any program already resides in the device is a good host. A good candidate should be ctlpnl.exe as documented in MSDN example.

I was soon disappointed. Nope!! ctlpnl.exe does not work! Although I killed ctlpnl.exe using the remote process viewer, the VS2005 debugger still quickly terminates the debug session, because ctlpnl.exe unloads my CPL as soon as it loads it, then itself immediately dies.

4. mstli.exe ==> the good guy

After some digging, I found mstli.exe is the good one. It perfectly loads my CPL, waits for my click on the device, then stops at my breakpoint. I tested in my Sprint Smartdevice PPC6601 (Windows Mobile 2003SE), Sprint Smartdevice PPC6700 (Windows Mobile 5.0), Pocket PC 2003 emulator, Pocket PC 5.0 emulator, all work well.

One caveat: Looks like mstli.exe is started once the device is up and running. So it must be killed before the debugger can start it. I use the remote process viewer to kill it.

Category: [Control Panel]

Pocket PC Power Management Series 4: A Better Way to Catch when the Device Wakes Up

2005-11-09T20:09:00.000-08:00

Pocket PC Power Management Series 4: A Better Way to Catch when the Device Wakes Up

In Pocket PC Power Management Series 3, I presented a simple program that depicts when the device runs and when it sleeps. The program uses a rudimentary and inefficient way to achieve the purpose: It spawns a periodically sleeping thread, which is responsible for recording whether itself sleeps through the predefined time frame. If it sleeps longer than expected, it draws the conclusion that the device must have been suspended.

The recommended and efficient way is to use the omnipotent CeSetUserNotificationEx API. If you happen to write any serious Windows Mobile programs, you must either have heard about it, or have used it. Basically it allows the developer to either launch a program, or to display a dialog, or to emit a sound, or to vibrate the device, if certain predefined system events occur, or if the predefined time arrives. I believe the Alarm program shipped with any Pocket PC or Smartphone (for example, the devices I have at hand: Sprint SmartDevice 6600, Sprint SmartDevice 6700, Palm Treo 700w, Cingular 8125, I-Mate SP5, Cingular MPx220, Sprint Samsung i600) must be written based on this API.

Luckily enough, Microsoft includes device wakeup event as one of the system events. The way to make use of the event is a little tweaked, so here is my example and source code, with detailed explanations.

1. Two helper functions to deal with wakeup Notifications: AddWakeupNotification and ClearWakeupNotification

AddWakeupNotification anticipates a constant string, which is the event name. Such name is also used later as the name of an event, as described in msdn documentation for CeSetUserNotificationEx and CE_NOTIFICATION_TRIGGER.

One notorious side-effect of CeSetUserNotificationEx is that the notification will be persisted in a central repository, unless the creator remembers to remove it. I've seen a couple of novice developers forgot to clear the notifications and subject his/her testing device to some really weird behaviors. So I also present ClearWakeupNotification, which also accepts a constan string.

static HRESULT AddWakeupNotification(LPCTSTR szEventName)
{
  HRESULT hr = S_OK;
  HANDLE hNotify = NULL;

  // set a CE_NOTIFICATION_TRIGGER
  CE_NOTIFICATION_TRIGGER notifTrigger;
  memset(&notifTrigger, 0, sizeof(CE_NOTIFICATION_TRIGGER));
  notifTrigger.dwSize = sizeof(CE_NOTIFICATION_TRIGGER);

  TCHAR szNamedEventName[MAX_PATH];
  memset(szNamedEventName, 0, sizeof(TCHAR)*MAX_PATH);
  _tcscat(szNamedEventName, NAMED_EVENT_PREFIX_TEXT);
  _tcscat(szNamedEventName, szEventName);

  notifTrigger.dwType = CNT_EVENT;
  notifTrigger.dwEvent = NOTIFICATION_EVENT_WAKEUP;
  notifTrigger.lpszApplication = szNamedEventName;
  //notifTrigger.lpszArguments = NULL;

  // set the notification
  hNotify = CeSetUserNotificationEx(0, &notifTrigger, NULL);
  // NULL because we do not care what action to take

  if (!hNotify) {
   hr = E_FAIL;
  } else {
   // close the handle as we do not need to use it further
   CloseHandle(hNotify);
  }

  return hr;
}

static HRESULT ClearWakeupNotification(LPCTSTR szEventName)
{
  HRESULT hr = S_OK;

  TCHAR szToCompare[MAX_PATH];
  memset(szToCompare, 0, sizeof(TCHAR)*MAX_PATH);
  _tcscat(szToCompare, NAMED_EVENT_PREFIX_TEXT);
  _tcscat(szToCompare, szEventName);

  // hold a notification
  PBYTE pBuff = (PBYTE)LocalAlloc(LPTR, 8192);

  if (!pBuff) {
      return E_OUTOFMEMORY;
  }

  // at most 256 notification handles -
  // should be more than enough for a typical device
  HANDLE hNotifHandlers[256];
  DWORD nNumHandlers = 0;
  DWORD i = 0;
  int rc = CeGetUserNotificationHandles(hNotifHandlers,
  dim(hNotifHandlers), &nNumHandlers);
  if (!rc) {
      hr = E_FAIL;
      goto FuncExit;
  }

  // iterate all notifications
  // Notice: We do not care about the status of the notification.
  // Just clear it even if it is not filed??
  for (; i<nNumHandlers; i++) {
      // query info for this specific handler
      BOOL bClearThis = FALSE;
      DWORD dwSize = 0;
      rc = CeGetUserNotification(hNotifHandlers[i], 8192, &dwSize, pBuff);
      if (!rc) continue;

      PCE_NOTIFICATION_INFO_HEADER pnih = (PCE_NOTIFICATION_INFO_HEADER)pBuff;
      PCE_NOTIFICATION_TRIGGER pNotifTrigger = pnih->pcent;

      // Notice some events with NULL lpszApplication might be inserted!
      if (pNotifTrigger && pNotifTrigger->lpszApplication
          && !_tcsicmp(pNotifTrigger->lpszApplication, szToCompare)) {
          CeClearUserNotification(pnih->hNotification);
      }
  }

FuncExit:
  if (pBuff) {
  LocalFree(pBuff);
  }

  return hr;
}

2. Wait for the named event

In Windows, events are named. What we need to do here is to create such a named event, and request that the notification subsystem set the named event when the notification event occurs. So the code skeleton is like this:

HRESULT hr = AddWakeupNotification(g_szEventName);
HANDLE hWakeupEvent = CreateEvent(NULL, TRUE, FALSE, g_szEventName);

// some code to wait for the named event
// -- meaning the device just wakes up
// ...

CloseHandle(hWakeupEvent);
hr = ClearWakeupNotification(g_szEventName);

The tricky part is how to wait for the wakeup event. If you really hates multi-threaded programming, I have the following single-thread example for your reference:

HANDLE eventHandles[] = {hWakeupEvent};
DWORD dwEventCount = 1;

TCHAR szBuf[256];
MSG currentMsg;

while (true) {
   ResetEvent(hWakeupEvent);
   DWORD dwRC = MsgWaitForMultipleObjectsEx(dwEventCount,
                   eventHandles, INFINITE, QS_ALLEVENTS, NULL);
   if (WAIT_OBJECT_0 == dwRC) {
       ALERT(TEXT("Aha Wakeup just now!));
   } else if (WAIT_FAILED == dwRC) {
       // XXX wait failed?
   } else if (WAIT_OBJECT_0+dwEventCount == dwRC) {
       int nGetMsg = GetMessage(&currentMsg, NULL, 0, 0);
       if (nGetMsg > 0) {
           TranslateMessage(&currentMsg);
           DispatchMessage(&currentMsg);
       } else if (nGetMsg < 0) {
           // XXX GetMsg failed;
       } else {
           break;
       }
   }
}

Read the above code, you'll find the familiae bolier plate code TranslateMessage() and DispathMessage(). Yes it is right! You can use MsgWaitForMultipleObjectsEx to both respond to the current thread message queue and listen to a list of events. In Windows, a window is associated with a thread, the thread that creates the window. So the "thread message queue" actually is your familiar "windows message queue". Use the powerful MsgWaitForMultipleObjectsEx API, you can achieve the purpose using only one thread to deal with UI, and listen to the wakeup event.

However, the above technique might not work well, and you may notice you'll frequently miss a wake-up event. The reason is obvious. The single thread most probably is processing a windows message (remember the two function calls: TranslateMessage and DispathMessage). If this thread is executing a windows procedure (because of a windows message) when the device wakes up, the thread for sure will miss the wakeup signal!

So a reliable way is to spawn a new thread, and use WaitForSingleObject to listen to the wakeup signal. Of course this thread does not necessary only deal with the wakeup signal. You can make it run other errands by calling WaitForMultipleObjects, but just make sure it should not be a busy thread!

Update: I uploaded series 10 with the two-thread code. The Visual Studio 2005 solution can be downloaded as well.

Category: [Power Management]

Pocket PC Power Management Series 3: When is My Device Sleeping, and when is it Running?

2005-10-30T19:12:00.000-08:00

Pocket PC Power Management Series 3: When is My Device Sleeping, and when is it Running?

I have seen too many people asking these questions: I want to query the OS to determine how much time before the device goes into sleep. Or, I want to get notified when the device is going to sleep. Well, conceptually it is not possible. Let us say OS generates such an event that it is going to sleep, and you write an event listener to perform some tasks. Guess what? Your event listener even does not get a chance to run, because the device falls asleep!

To help understand the pattern how the device runs-sleeps-runs-sleeps, I wrote a program that records when the device falls sleep and prints out a simple diagram showing what time the device is running, and what time the device is sleeping. You can download the program from your Pocket IE, or from your desktop browser then copy it to your device. The program can only run in Windows Mobile devices, not on desktop.

Below are three screen cuts taken when the program runs in my device. Each screen cut shows how long the device runs and how long it sleeps, and draw two lines reflecting when it runs and when it sleeps. Take a closer look at the third screen cut, when the device was put onto my table unattended for a night. The device only runs for 6614/63598=10% of the time. That is Microsoft's way to save battery, and ironically, it did not work well for a few programs, for example, the ones I am trying to tackle in my Power Management series...

How the program works? Basically there are two threads. One thread is responsible for updating the UI based on an internal data structure. The other thread simply sleeps periodically at a predefined interval; each time it wakes up, the thread tests whether it has slept through the predefined interval. If the device is suspended, the sleeping thread could find that it has slept for a time longer than expected, so it figured out the device must have fall asleep, and update the internal data structure accordingly. Notice this is an inefficient way to test whether a device is slept. I plan to discuss a much better one in my next post.

APIs and technique used in the program:

- Get the current time in seconds, using GetLocalTime and SystemTimeToFileTime

- Compare two ULONGLONG structures. A ULONGLONG is essentially two DWORDs.

- Basic threading code: CreateThread, and how to gracefully shutdown a sleeping or running thread

- Basic thread communication mechanism: CreateEvent, PulseEvent, WaitForSingleObject

- InterruptibleSleep: a sleep that can be gracefully interrupted at anytime by using WaitForSingleObject, rather than the plain vanilla Sleep()

Category: [Power Management]

Pocket PC Power Management Series 2: Problem Domain

2005-10-12T12:52:00.000-07:00

Pocket PC Power Management Series 2: Problem Domain

Most UI-intensive applications require the user to interact via a screen UI using stylus or keyboard. For such applications, it does not make sense to run it when the device is suspended, or “in sleep mode”. What a developer needs to do is to avoid burning any CPU cycles when the device is sleeping or, to be more exactly, when the user is not interacting with the application (for example, its main window is not the foreground window.) Mike Calligaro from Microsoft Windows Mobile Team has two excellent articles on this topic with good examples. I strongly recommend readers to go over those two posts:

The problem we are trying to solve here belongs to another domain: What if the application needs to run continuously, or at least, needs to run periodically independent of the user’s action? It runs if the user puts the device unattended, it runs if the user sometimes powers the device on and turns it off quickly, and it runs when the device is put into a charger (of course).

A media player or a MP3 player is a great example of applications that needs to run continuously. A stock-alert application is a good example of applications that needs to run periodically.

Thinking about a stock-alert program that needs to constantly (if not continuously) monitor a stock symbol and alerts the user if the price is higher (or lower) than a predefined threshold value. Such program is a piece of cake in desktop windows, where you may simply write a monitoring thread and assume the thread can run all the time and continuously read stock price from a public server. The same piece of cake becomes sour if running in Pocket PC devices, since the monitoring thread might not get a chance to run for a long time, and you may miss an alert!

Keep in mind battery is precious in a handheld device, so you need to strike a balance between two conflicting factors: to make the system run thus consuming batteries vs. to save battery for the device. The general principle is still the same: to consume CPU cycles as less as possible.

If the application needs to run unattended, turn off the screen display by all means.
If the application does not need to run continuously, make it run periodically.
If the application does not need to run periodically, but needs to catch user’s stylus action as quickly as possible once the device is switched on, listen to a Wakeup event.

Category: [Power Management]

Pocket PC Power Management Series 1: the Challenge to Developers

2005-09-26T00:07:00.000-07:00

Pocket PC Power Management Series 1: the Challenge to Developers

If you own a Pocket PC, you may notice that its screen frequently turns off, if the device is not used for certain time. The time can be adjusted via “Start => Settings => System => Battery => Advanced”. By default it is 3 minutes.

To turn off the screen is a good thing to the battery life, as the LCD display often turns out to the big battery sucker, especially if backlight is configured to be very bright. However, for some reason, Microsoft deemed that to turn off the CPU might save even more battery. So here comes a unique power model in Pocket PC: The system is also suspended after the device is not used for certain time. Or we say the system is sleeping, in sleep mode.

When the system is “suspended”, or when the device is “sleeping”, all threads are suspended. Let us say you have a nicely written application that has a great UI (controlled by one thread) and a hard-working background thread that analyzes storage data and also interacts with the UI thread. When the system is suspended, neither of your two threads gets a chance to run.

When the devie is sleeping, THE THREADS SIMPLY DO NOT RUN! Period.

Compared to a desktop machine, if the machine is not used for certain time, a screen saver may be started, or the power management system may kick in and turn off the screen. Whatever, the CPU is still spinning; any of your threads can still run as usual.

Such unique power model in Pocket PC presents unique challenge to developing programs that need to run for a long time uninterrupted (or need to run even if the system is suspended). I’ll come up with a few blog posts soon on how to write such a program, mainly:

General principles
Force the device to run?
Request the device to run?
GetTickCount vs GetLocalTime
Older notification functions
Newer notification functions

Please notice the smartphone series does not have such power model. Smartphone is more like destkop windows. A smartphone either runs all the time, even if the SCREEN is turned off, or does not run at all, when the phone is turned off.

Category: [Power Management]

InterProcess Communications in Windows Mobile

2005-09-09T21:00:00.000-07:00

Here are the possible methods. Will expand the content later...

SendMessage
PostThreadMessage
SharedMem file-mapping
registry, filesystem

Manually migrate Embedded Visual C++ workspace to Visual Studio 2005 (Beta 2) without using Migration Assistant (Upgrade Wizard)

2005-08-25T18:53:00.000-07:00

Manually migrate Embedded Visual C++ workspace to Visual Studio 2005 (Beta 2) without using Migration Assistant (Upgrade Wizard)

My Embedded Visual C++ 4.0 workspace has more than 10 projects. Some projects are built into EXEs, some DLLs, some static linked libs, and one CPL. If working within EVC IDE I use "batch build" to generate all the binaries, then call a .bat to generate a CAB file. Outside the IDE (for example, overnight build), I have an Ant script that calls "evc" command line to generate binaries and the CAB file.

Recently I obtained a copy of Visual Studio 2005 Beta 2 DVD. So I need to migrate the EVC4 workspace to VS2005.

Microsoft published an article to help migrate the EVC workspace to VS2005 as a solution. You may have two choices:

Using MS-provided "EVC Upgrade Wizard" (download here), which is a Visual Studio Addon. I downloaded a copy and read the installation .bat file. I was scared, as the so-called Visual Studio Addon needs to REPLACE a bunch of existing DLLs, rather than adding some ADDITIONAL DLLs. (So Addon looks like is not a good name.)
Manual migration. This turns out to be a rough road, and that article apparently does not help much.

Here it is a recoup of what I did for the manual migration. As a starting point, I picked one project which builds a simple DLL and has no dependency on other projects. I first created an empty solution, and then add a project by choosing the following from "Add New Project" dialog:
Visual C++ => Smart Device => Win32 Smart Device Project

This pops up a "Win32 Smart Device Project Wizard" dialog, in which I choose "DLL" and "Empty project". VS2005 created the .vcproj file and then I started to add the source files to this project.

Before building the solution, of course some common project settings need to be transferred. For example, "Addtional Include Directories", "Additional Dependencies", and "Ignore Specific Library" (OLDNAMES.lib).

Notice that I did not copy the "Preprocess Definitions" from EVC++ to VS2005. The system-provided definitions are actually a bit different. For example, in VS2005, "_DEBUG" is defined along with "DEBUG", inline with WIN32 desktop project. Also "$(CePlatform)" and "$(CEVersion)" are replaced by "$(PLATFORMDEFINES)" and "$(CEVER)" respectively. (From the command line, you could easily figure out how VS2005 is expanding them: /D "_WIN32_WCE=0x420" /D "WIN32_PLATFORM_PSPC")

Next I kicked start "Build". I was glad to find that all source files build successfully, but linker seems not happy. It printed out zillions of errors that I'd never seen before in my EVC++ environment. Luckily all errors belong to either of the following two:

- error LNK2001: unresolved external symbol __security_check_cookie, or error LNK2001: unresolved external symbol __security_cookie

- error LNK2001: unresolved external symbol "const type_info::`vftable'" (??_7type_info@@6B@), or error LNK2001: unresolved external symbol "void __cdecl `eh vector destructor iterator'(void *,unsigned int,int,void (__cdecl*)(void *))" (??_M@YAXPAXIHP6AX0@Z@Z)

So linker is not happy as it could not find some libraries or object files. As usual, Microsoft help does not provide good information, so I googled a few links.

Linker Error 1. __security_check_cookie & __security_cookie

There is actually an MS KB for this issue. Out of good intention, Microsoft compiler injects some code to detect (but not to prevent) buffer overflow attack. Apparently "__security_cookie" is one function call the complier injects. The KB articles suggests adding "BufferOverflowU.lib" to the library list. However, looks like there is simply no such file under the wce420 (Windows Mobile 2003) SDK directory. The other walkaround is to remove "/GS" switch (or define "/GS-") to instruct the compiler not to inject the code. You could achieve this via "Project Settings"=>"Configuration Properties"=>"C/C++"=>"Code Generation"=>"Buffer Security Check" set to "No".

Thinking that I should give it a try and retain this buffer overflow detection capability, I did a binary-content search under wce420/lib folder, and find "secchk.lib" contains those two functions. So I add this lib to the dependencies list.

Linker Error 2. const type_info::`vftable'" (??_7type_info@@6B@)

This has something to do with exception handling, which needs dynamic cast (RunTime Type Information, dynamic_cast, typeid, and type_info). MS has a KB article instructing where to download RTTI library for Windows Mobile 2003 devices. I did a binary-content search again, and found the library "ccrtrtti.lib" under Windows Mobile 2003 SDK. So I just simply add this lib to the dependencies list.

Please notice that the above two libraries are not available from the Windows Mobile 2003 SDK download, but they do apprear in the SDK directory shipped along with VS2005.

After I manually add "secchk.lib" and "ccrtrtti.lib" to the additional dependency list, linker is happy, and all 20-around projects build successfully.

Category: [Development Environment]

Windows Mobile Pocket PC Smartphone Programming: SiteMap

2005-08-10T23:31:00.000-07:00

Windows Mobile Pocket PC Smartphone Programming: SiteMap

Introduction

2005-08-05T19:48:00.000-07:00

Here is my short profile.

Here is the SiteMap categorizing all my articles for easy navigation. Google's blog is great in the sense that the blog writer has full control over the format and presentation of the posts. However, lacking category is a huge drawback, and makes it very difficult to navigate through the articles. A site map page is an valuable tool for readers.

My daily job involves java design and programming for generic platforms, and C++ coding for Windows and Windows Mobile devices.

Goal of the Blog

As a C++ and Java coder, I am new in blogging. The niche topic I picked for my blog is the one with which I am familiar: Windows Mobile Pocket PC Smartphone Programming. I tried hard to write original contents, rather than easy re-blogging or quick short articles with a few links. Most of the posts were based on my daily programming and problem solving experiences, and may not publicly documented anywhere else. For example, how to put a Pocket PC Control Panel Applet into the "Personal" group, how to programmatically query mail account information (like username and server name). A google search might land only one result, which is my post here :) Hope my hard work can benefit the Windows Mobile developer community. If you find a post helpful, or have errors/problems/incompleteness, please take a few seconds to drop a comment, which serves as great stimulus to me.

One goal of the blog is tailor to programmers. I tried to put as many lines of source code as possible. Those source codes are written and tested by me. Whenever possible, a VS2005 solution or EVC4 workspace is available for download. Some source codes are only snippets, appearing as part of an article. A decent programmer should have little difficulty writing a program using my source code, probably by adding header-file-includes and macro definitions.

I take pride in my hard work. I hope you can bookmark my site (typing Ctrl-D now), or add the site feeds to your news reader:

I also hope you appreciate my hard work. If you need to use or refer to any post, please provide a link to this site (preferred) or to the specific post.

A little bit on my Personal Life

Outside the technology world, I am interested in cars, dinosaurs, wild life, prehistoric life, human evolution, science fiction, adventure movies, and etc. I am a big fan of star wars series and lord of the rings series. I am also a super fan of dinosaurs.

My wife and I are living happily in the sunny Bay Area. Our baby girl was born in June 2005. She is the loveliest angel in the world, oh, make it “in my world”. I have never had such strong, devoted, unconditional love toward any other people, except my baby girl. Look at how lovely her smile is...

Again, I have been trying hard to find time to post articles to my blog, and trying harder to promote my site. If you like my site and articles, and would like to swap a link, feel free to drop me a line. Comments or feedbacks on my articles are very welcome. I am watching my inbox and comments all the time!