Calling Driver Methods and Properties

It is common to invoke driver methods and properties within the implementation of other methods and properties. For example, high-level configuration functions, such as the IIviRFSigGenFM::Configure defined in the IviRFSigGen class specification, often rely upon lower-level driver properties for their implementation. When such properties are called from another driver method, it is very important that the properties are called using the syntax described below.

Important
If driver methods and properties are invoked from within the driver in any fashion other than that described in this topic, a wide variety of unpredictable results may be observed. These errors will not be detectable at compile time.

The format for properly invoking a driver method or property from another driver method or property is as follows (note the leading underscore is required):

_<interface>::<method>

or, for a property put operation

_<interface>::<put_property>

or, for a property get operation

_<interface>::<get_property>

The reason it is so important to invoke methods and properties in this way is that the above syntax ensures the method call goes through the Nimbus generated pre-processing and post-processing code in the ForwardingShims.nimbus.cpp file. The code in this file provides a wide variety of important services, such as parameter validation, thread safety, range checking, state caching, and more. Directly calling a driver method or property in any other fashion completely bypasses all of this important logic.

The code sample below demonstrates the proper way to invoke driver methods from within the driver implementation.

HRESULT Acme4321::IIviRFSigGenFM_Configure(BSTR Source, double Deviation)
{
   HRESULT hr = S_OK;

   hr = _IIviRFSigGenFM::put_Source(Source);
   if (SUCCEEDED(hr))
   {
      hr = _IIviRFSigGenFM::put_Deviation(Deviation);
   }

   return hr;
}

The code sample belows shows some INCORRECT ways to invoke driver methods from within the driver implementation.

HRESULT Acme4321::IIviRFSigGenFM_Configure(BSTR Source, double Deviation)
{
   HRESULT hr = S_OK;

   /// WRONG!! WRONG!!! WRONG!!!
   /// This will compile, but may not behave as expected.
   hr = put_Source(Source);

   if (SUCCEEDED(hr))
   {
      /// WRONG!! WRONG!!! WRONG!!!
      /// This will also compile, but may not behave as expected.
      hr = Acme4321::put_Deviation(Deviation);
   }

   return hr;
}