Creating Events for Asynchronous Functions

Article
03/13/2008

Several functions provided by the Active Directory Rights Management Services (AD RMS) SDK operate asynchronously. These functions operate asynchronously because they must acquire something—a license, a revocation list, and so on—from a remote source not under the control of the client. In some cases this can be fairly time consuming. To handle this, the SDK functions create a second thread to handle the return of the acquired object and continue processing the code. If the asynchronous request does not occur within a specified period of time, the work thread updates the callback function with an error message and exits. You may want to consider creating event handlers that wait for a success or failure code.

The following examples show how to create events to control program flow using asynchronous functions.

This example comes from the function calling the asynchronous function. It creates an event object and passes the event for the pvContext parameter of DRMAcquireLicense. For this to work, the callback function must have some corresponding code, which is shown in the second example.

// The wait time is actually passed to the function in milliseconds.
#define WAIT_TIME_IN_SECONDS         60 * 1000
...
HANDLE  hEULAcquired = NULL;    // Handle for your new event

// Creation function for your event.
hEULAcquired = CreateEvent(NULL, FALSE, FALSE, NULL);
if(NULL == hEULAcquired)
{
hr = E_FAIL;
goto e_Exit;
}

// Now run the asynchronous function, passing in the event in pvContext, 
// which can hold anything. The code will wait here until the callback function
// signals that the task is complete, or until the specified wait time is exceeded. 
hr = DRMAcquireLicense( 
                        hLicenseStorage,
                        0,
                        NULL,
                        NULL,
                        NULL,
                        NULL,
                        &hEULAcquired 
                      );
if (WAIT_OBJECT_0 != WaitForSingleObject(
                        hEULAcquired, 
                        WAIT_TIME_IN_SECONDS ))
{// Did not complete in the desired time frame.}
...

In the callback function, you have a way of signaling that the event is complete. The following example shows how to signal to WaitForSingleObject that your event is complete.

HRESULT __stdcall OnStatus( DRM_STATUS_MSG msg, 
                         HRESULT hr, 
                         VOID *pvParam, 
                         VOID *pvContext )
{
HANDLE *phEvent = NULL;  // Holds a pointer to your event.
// Point your event handle to pvContext.
 if(pvContext)
 {
     phEvent = (HANDLE*)pvContext;
 }
...
if( msg == DRM_MSG_ACQUIRE_LICENSE && 
           (hr == S_DRM_COMPLETED || FAILED(hr))  )
{
    // Tell the event the process is complete.
    SetEvent(*phEvent); 
}
...

In the previous callback code, you should check for all possible returned message values.

For more information about events, see Event Objects.

Share via

Creating Events for Asynchronous Functions

See Also

Additional resources