GetIAsyncMessagePointer

ppAsyncMessage

[out] IAsyncMessage pointer.

Returns S_OK if successful, otherwise a failure HRESULT.

This function returns an IAsyncMessage pointer to the current VISA-COM I/O session. This can be useful for accessing VISA-COM functionality not directly exposed in the Nimbus Template Library. Also, the IAsyncMessage pointer can be passed out of the driver to the client application so that end users can directly manipulate aspects of the I/O session.

Caution

The pointer returned by this function is a referenced-counted COM interface pointer. Calling this function increments that reference count, so it is critical that the caller receiving the pointer properly call Release on the interface pointer. If the pointer is passed out of the driver to a client application, then it is the responsibility of the client application to properly release the pointer. Failure to properly manage this interface pointer will cause the entire VISA-COM I/O session to leak memory.

The following example demonstrates use of the GetIAsyncMessagePointer function.

// CoAcme4321.cpp
HRESULT Acme4321::OnFinalInitialize()
{
  HRESULT hr = S_OK;

  CComPtr<IAsyncMessage> spAsyncMessage;
  hr = io.DirectIo.GetIAsyncMessagePointer(&spAsyncMessage);

  // Note that the CComPtr smart pointer class automatically calls release when the function exits

  return hr;
}