Determining if an API is Ready
A version of this page is also available for
4/8/2010
Modules that expose an interface can use a named event to indicate readiness. Modules that need to use the interface can wait for the named event. This event is registered through a setting in the registry, so that the OS can indicate whether or not the interface is ever going to be ready.
The following table describes the ways that you can determine if an API is ready on all platforms.
| API | Description |
|---|---|
You can use API ready events to determine if an API would never be ready, that is, it is not part of the OS design. Ready events can be useful if you want to write code that runs on multiple types of devices, where one implements a particular API set and another does not. For example if your application chooses whether or not to display UI, based on whether the Graphics, Windowing, and Event Subsystem (GWES) API set is ever going to be registered, so that it can run on devices with displays, as well as devices without displays. |
If it is best to block until the notification API is ready to guarantee that the notification is not lost, and then use OpenEvent or WaitForSingleObject. OpenEvent fails if the API is never going to be ready. Once OpenEvent fails or WaitForSingleObject returns, you know the state of the notification API.
Example
// This is not an OS type, just a type defined for this sample code
typedef enum
{
APISTATE_UNKNOWN,
APISTATE_NEVER,
APISTATE_NOT_READY,
APISTATE_READY
}
ApiState;
// Use whatever event name defines the state of readiness for the API set that needs to be used. In this case it is the GWE API set.
#define EVENT_NAME TEXT("SYSTEM/GweApiSetReady")
// Uses an API if it's ready, waits for it if it's not ready
void UseAnAPIWithWaiting()
{
static ApiState state = APISTATE_UNKNOWN;
HANDLE hEvent;
if (state == APISTATE_UNKNOWN)
{
hEvent = OpenEvent(EVENT_ALL_ACCESS, 0, EVENT_NAME);
if (hEvent)
{
// Wait for the API set to be ready.
aitForSingleObject(hEvent, INFINITE);
CloseHandle(hEvent);
state = APISTATE_READY;
}
else
{
// The API set will never be ready.
state = APISTATE_NEVER;
}
}
if (state == APISTATE_READY)
{
// Now, use the API set.
}