Implementing IVI-C-Only Functions and Attributes

One of the most common scenarios for manually implementing IVI-C functions is high-level "configure" functions. By convention, IVI drivers typically define a Configure function to set the values of attributes. The syntax for directly reading and writing IVI-C attributes via attribute accessors is somewhat cumbersome for end users, so IVI recommends that Configure functions be made available as well.

The following example demonstrates how to implement an IVI-C function in terms of an IVI-C attribute:

ViStatus _VI_FUNC acme4321_ConfigureAcquisitionType ( ViSession Vi, ViInt32 AcquisitionType )
{
    ViStatus status = VI_SUCCESS;

  status = acme4321_SetAttributeViInt32(vi, VI_NULL, ACME4321_ATTR_ACQUISITION_TYPE, AcquisitionType);

    return status;
}

As mentioned previously, the default mode for Nimbus is to implement IVI-C functions in terms of the associated IVI-COM method or property (except, of course, in the case of IVI-C-only functions). The best way to understand how to manually implement an IVI-C function in terms of IVI-COM methods and properties is by examining a Nimbus-generated implementation from the <prefix>.nimbus.cpp file.

The following code demonstrates how to implement the IVI-C function ConfigureEdgeTriggerSource in terms of the IVI-COM method IIviScopeTriggerEdge.Configure:

ViStatus _VI_FUNC acme4321_ConfigureEdgeTriggerSource ( ViSession Vi, ViConstString Source, ViReal64 Level, ViInt32 Slope )
{
    ViStatus status = VI_SUCCESS;
    CComPtr<IIviScopeTriggerEdge> spTriggerEdge;
    status = GetDriverInterface(Vi, &spTriggerEdge);
    if (status == VI_SUCCESS)
    {
        CParam<ViConstString> _Source(Source);
        CParam<ViReal64> _Level(Level);
        CParam<ViInt32> _Slope(Slope);
        HRESULT hr = spTriggerEdge->Configure(_Source, _Level, (IviScopeTriggerSlopeEnum)(long)_Slope);
        status = TranslateHRESULT(Vi, hr);
    }

    return status;
}

The first task performed by the above code is to obtain a pointer to the appropriate interface on the IVI-COM driver. In this case, the Configure method we are after resides on the IIviScopeTriggerEdge interface. This interface is accessed by calling the GetDriverInterface helper function provided by Nimbus. The interface pointer is returned from this function and stored in a CComPtr smart pointer variable named spTriggerEdge. Using CComPtr ensures that the reference to the interface is automatically released when the function exits.

The code then checks the status returned from GetDriverInterface, and, if successful, it sets up the three temporary input parameters (_Source, _Level, and _Slope) that will be passed to the IVI-COM Configure method.

The three temporary parameters (declared as CParam objects) are templatized based on the IVI-C parameter type and serve a very important role -- they automatically perform the data type conversions from the IVI-C input parameters to their COM equivalents. For instance, the Source parameter passed to the acme4321_ConfigureEdgeTriggerSource function is of type ViConstString. However, the corresonding IVI-COM method accepts the COM BSTR data type for its Source parameter. The IVI-C parameter cannot simply be passed directly to the IVI-COM method -- it must be converted from ViConstString to BSTR. This task is performed by the CParam helper classes provided by Nimbus. The CParam class can be used to convert between any two compatible IVI-C and IVI-COM data types.

With the appropriate CParam objects declared, the IVI-COM Configure method is invoked using the spTriggerEdge smart pointer. IVI-COM methods always return an HRESULT to indicate success or failure. They also populate a "hidden" COM error object that contains additional error information, such as a string description of the error that occurred. This information must be translated into a form that IVI-C clients can consume. This is the role of the TranslateHRESULT helper function provided by Nimbus. This function converts the HRESULT into a corresponding IVI-C ViStatus value. It also harvests the error description from the COM error object and stores it in the IVI-C session so that client calls to the IVI-C GetError function will return the appropriate message.

There are two techniques used for returning errors from IVI-C functions. The TranslateHRESULT function described above is always used when the IVI-C function is implemented by delegating to an IVI-COM method or property. The other option is to use the ReportError function with an explicit IVI-C error name and description.

The following code demonstrates use of the ReportError function to validate parameters passed to an IVI-C function.

ViStatus _VI_FUNC acme4321_FetchWaveformMeasurement ( ViSession Vi, ViConstString Channel, ViInt32 MeasFunction, ViReal64* Measurement )
{
    if (Measurement == VI_NULL) return ReportError(Vi, ACME_ERROR_NULL_POINTER, _T("Parameter Measurement is VI_NULL."));

    ViStatus status = VI_SUCCESS;

    // ...

    return status;
}

The code in the above example uses ReportError to report a NULL-pointer error for the Measurement output parameter.