GetIMessagePointer

Retrieves an IMessage pointer from the VISA-COM I/O session.

Syntax

virtual HRESULT GetIMessagePointer(IMessage** ppMessage) override;

Parameters

ppMessage

[out] IMessage pointer.

Return value

Returns S_OK if successful, otherwise a failure HRESULT.

Remarks

This function returns an IMessage 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 IMessage 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.

Example

The following example demonstrates use of the GetIMessagePointer function.

CoAcme4321.cpp

HRESULT Acme4321::OnFinalInitialize()
{
  HRESULT hr = S_OK;

  CComPtr<IMessage> spMessage;
  hr = io.DirectIo.GetIMessagePointer(&spMessage);

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

  return hr;
}