Windows CE: Determining if an API is Available

Many Windows CE systems are kiosk type devices, where the Software running on the systems starts when the system boots. This causes a new problem for some software developers: the API may not be ready to be used when the software starts. To add to the fun, not all Windows CE systems are equal so some APIs may never become available.

Early versions of Windows CE provide a simple method to determine if an API is available, the function IsAPIReady(). IsAPIReady() is a handy method to determine if an API is ready, but it requires that the code that calls it poll until the API is ready. Polling is inefficient, especially on a battery powered device. Example of IsAPIReady:

                // Wait for the Window Manager API set to become available

                while (!IsAPIReady(SH_WMGR))

                {

                                Sleep(200);

                }

In later versions of Windows CE, at least by CE 4.2 (but I couldn’t confirm or deny earlier versions) WaitForSingleObject() can be used in conjunction with a named event. This has two advantages; no polling and determines if the API will ever become available. Example:

                DWORD RetVal = 0;

                HANDLE hWMGREvent;               

 

hWMGREvent = OpenEvent(EVENT_ALL_ACCESS, FALSE, TEXT("system/events/notify/APIReady"));

               

                if( !hWMGREvent )

                {

                                RETAILMSG( 1, (TEXT("Failed to open hWMGREvent %d/n"), GetLastError() ));

                                // API will never become available so handle that here.

                }

                else

                {

                                RetVal = WaitForSingleObject( hWMGREvent, INFINITE );

                                if( RetVal == WAIT_OBJECT_0 )

                                                RETAILMSG( 1, (TEXT("/n---WMGR is ready/n")));

                                else

                                                RETAILMSG( 1, (TEXT("WMGR Error %d/n"), GetLastError() ));

                                CloseHandle( hWMGREvent );

                }

The event names are listed in the registry under HKEY_LOCAL_MACHINE/Events. In this case the entry is:

[HKEY_LOCAL_MACHINE/SYSTEM/Events]

    "system/events/notify/APIReady"="Notifications API set ready"

Where system/events/notify/APIReady is the event name and “Notifications API set ready” is a description of the event.

Starting with Windows CE 6.0, WaitForAPIReady() is added. WaitForAPIReady() is an interesting addition to the Windows CE API set.  Interesting becuase it really doesn't seem to add much value.   All it really does is replace the call to WaitForSingleObject(), but to determine if an API is included, the application must still call OpenEvent().

Example:

                if( WaitForAPIReady(SH_WMGR, INFINITE) == WAIT_OBJECT_0 )

                                RETAILMSG( 1, (TEXT("WFAR WMGR is ready.... /n")));

                else

                {

                                RETAILMSG( 1, (TEXT("WFAR failed %d/n"), GetLastError() ));

                }

The first parameter to WaitForAPIReady() is an identifier of the API to wait for. If your version of Platform Builder help tells you to look in pkfuncs.h for the ID, then go to MSDN for the latest documentation.

Copyright © 2009 – Bruce Eitman

All Rights Reserved