Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

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
Ready-Event Registration Ready-Event Process	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.

API

Description

Ready-Event Registration

Ready-Event Process

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 OpenEventor WaitForSingleObject. OpenEventfails if the API is never going to be ready. Once OpenEventfails or WaitForSingleObjectreturns, you know the state of the notification API.

Example

	Copy Code
// 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. }

Copy Code

// 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.
}

Example

See Also

Concepts

Other Resources