Asynchronous return handler

An asynchronous return handler is called from the CHAI when an asynchronous function is realized.

It is based on a set of interface classes whose name is suffixed with ***_AsyncReturnHandler.

An application starting an asynchronous function must implement the related asynchronous return handlers and pass its reference during the asynchronous method call.

Example of device enumeration:

CPNS::IAsync* m_pAsync;

...

m_pAsync = m_pCHAI->RemoteDevice_FindFirst_Async(
                           // Root device identity
                           CPNS::DeviceID::NullDeviceID,
                           // Included and excluded device capabilities
                           CPNS::Enums::DC_SmartConnectTarget, CPNS::Enums::DC_None,
                           // Notification handler 
                           this,
                           // User pointer 
                           NULL);

Note

The return handler will always be called , even in case of failure.

m_pAsync value is identifying the asynchronous operation. It remains valid until the end of the related async return handler call.

A call to CPNS::ICHAI::CancelAsync(pAsync) can be performed to abort the asynchronous operation.

Example of device enumeration return handler:

void MyHandler::OnCHAI_RemoteDevice_Find_Return( 
  IN CPNS::IAsync * const pAsync, 
  IN CPNS::boolean const fSuccess, 
  IN CPNS::IRemoteDevice * const pRemoteDevice, 
  IN CPNS::IDeviceEnumerationContext * const pSearchContext )
{
  // Set m_pAsync at NULL since the operation is done.
  m_pAsync = NULL;
  if (fSuccess)
  {
    ... do something with pRemoteDevice
    
    // Find next device
    m_pAsync = m_pCHAI->RemoteDevice_FindNext_Async(pSearchContext, this, NULL);
  }
}

Note

A hooked object is always Acquired before being passed as an argument to an asynchronous return handler, and then Released on return of this handler. This is to ensure that the object will not be destroyed during the notification call. An application storing a pointer to a hooked object must acquire it and release it once it becomes useless.