Linking IVI.NET and IVI-C Methods and Properties

When IVI.NET items, such as methods, properties, parameters, and enums, are added to the driver hierarchy using the IVI.NET Designer, corresponding items are automatically added to the IVI-C hierarchy. For instance, adding an IVI.NET method automatically adds a corresponding IVI-C function. Since IVI.NET and IVI-C represent data types, repeated capabilities, and other driver characteristics differently, Nimbus must perform various transformations when mapping between IVI.NET and IVI-C. In situations where an IVI.NET item cannot or should not be represented in IVI-C, or vice versa, Nimbus provides a means to implement IVI.NET-only and IVI-C-only items. This topic explains important aspects of managing the relationship between the IVI.NET driver and its linked IVI-C driver.

The IVI-C ViSession Parameter

Every IVI-C function accepts a ViSession as its first parameter. The ViSession parameter identifies the instrument I/O session. Nimbus automatically adds a ViSession parameter to every IVI-C function it associates with an IVI.NET method. Inside the implementation of the IVI-C function, the Nimbus-generated code uses the ViSession parameter to locate the correct IVI.NET driver instance to call. The ViSession parameter cannot be deleted from an IVI-C driver function.

IVI.NET and IVI-C Return Types

IVI.NET methods may have a non-void return type. By contrast, IVI-C functions always return a ViStatus result. This means that if an IVI.NET method specifies anything other than void as its return type, an [out] parameter of the specified type must be added to the corresponding IVI-C function signature. Nimbus adds such an [out] parameter automatically when needed.

Mapping IVI.NET and IVI-C Data Types

When an IVI.NET method is associated with an IVI-C function, the method return type as well as the data type of each parameter must be mapped to an appropriate IVI-C data type. Similarly, an IVI.NET property type must be mapped to its corresponding IVI-C attribute type. Nimbus performs these transformations automatically when an IVI.NET method or property is created and when parameters are added. Most of these mappings are straightforward and are given in the table below:

IVI.NET Data Type	IVI-C Data Type
`Boolean`	`ViBoolean`
`String`	`ViConstString` (for [in] parameters) `ViString`, plus a BufferSize parameter (for [out] and [in,out] parameters) (See discussion below.)
`Byte`	`ViChar`
`Int16`	`ViInt16`
`Int32`	`ViInt32`
`Int64`	`ViInt64`
`Single`	`ViReal32`
`Double`	`ViReal64`
`TimeSpan`	`ViReal64`
`PrecisionTimeSpan`	`ViReal64`

Mapping Array Parameters

IVI.NET drivers use standard .NET arrays where the number and type of elements present in the array is maintained within the System.Array class itself. IVI-C drivers, however, use C-style arrays. Since C-style arrays are simply pointers, extra parameters must be used with an IVI-C array to indicate the number of elements present. The IVI specifications prescribe specific naming and ordering conventions for these extra “array size” parameters. Nimbus automatically manages these extra IVI-C parameters as follows:

When an array parameter is added to an IVI.NET method

An [in] parameter of type ViInt32 is added to the IVI-C function and placed just before the IVI-C array parameter. The parameter name is based upon the array parameter name, as follows:

\<arrayParamName\>BufferSize

This buffer size parameter is used to indicate how many elements (not bytes) have been allocated in the array by the caller. This helps ensure the function implementation does not try to access more elements than are available.
A C-style array is added to the IVI-C function to represent the SAFEARRAY data itself.
If the array parameter is an [in,out] parameter, then an [out] parameter of type ViInt32 is added to the IVI-C function and placed just after the IVI-C array parameter. The parameter name is based upon the array parameter name, as follows:

\<arrayParamName\>ActualSize

This actual size parameter is used to indicate how many elements (not bytes) were filled in by the function implementation. This indicates to the caller how much of the allocated space, as indicated by the buffer size parameter, was actually used.

Mapping String Parameters

Unlike IVI.NET drivers which use self-describing System.String types for string parameters, IVI-C drivers use character arrays (arrays of ViChar typedef’d to the ViString data type). When used as input parameters IVI-C strings do not need additional length parameters because the string is NULL-terminated and the length is easily determined by the function implementation. However, when strings are used as [out] parameters in IVI-C drivers, an additional buffer size parameter must be used to indicate to the function implementation how many characters have been allocated by the caller. The IVI specifications prescribe specific naming and ordering conventions for this extra “buffer size” parameter. Nimbus automatically manages this extra IVI-C parameter as follows:

When a string [out] parameter is added to an IVI.NET method

An [in] parameter of type ViInt32 is added to the IVI-C function and placed just before the IVI-C ViString parameter. The parameter name is based upon the ViString parameter name, as follows:

\<stringParamName\>BufferSize

This buffer size parameter is used to indicate how many characters have been allocated in the string by the caller. This helps ensure the function implementation does not try to access more characters than are available.
A ViString parameter is added to the IVI-C function to represent the System.String data itself.

Mapping TimeSpan and PrecisionTimeSpan Parameters

Because time-based values are quite common in IVI driver APIs, the IVI Foundation introduced the PrecisionTimeSpan data type. This data type provides much of the convenience of the standard TimeSpan data type available in the .NET Framework, but it offers higher timekeeping accuracy.

Nimbus provides special support for TimeSpan and PrecisionTimeSpan parameters. Whenever a parameter or property of either of those types is created in an IVI.NET driver, a ViReal64 parameter or attribute is created in the linked IVI-C driver.

Mapping IVI.NET and IVI-C Repeated Capabilities

IVI.NET and IVI-C have a few important differences in the way they represent repeated capabilities. The first difference of note is that IVI-C drivers do not support collection-style repeated capabilities. IVI.NET and IVI-C drivers also use a different set of IVI-defined standard methods and properties to manage the repeated capability instances.

The table below presents the required repeated capability methods and properties for IVI.NET and IVI-C drivers based upon the type of repeated capability. For a discussion of the different types of repeated capabilities see the IVI Backgrounder topic on Repeated Capabilities.

Repeated Capability Style	IVI.NET	IVI-C
Collection-Style	`Count` property `Item` property `Name` property	Not supported.
Parameter-Style	`<Capability>Count` property (Ex: `ChannelCount`)	`<CAPABILITY>_COUNT` attribute (Ex: `CHANNEL_COUNT`) `Get<Capability>Name` function (Ex: `GetChannelName`)
Selector-Style	`<Capability>Count` property (Ex: `ChannelCount`) `Active<Capability>` property (Ex: `ActiveChannel`) `Get<Capability>Name` method (Ex: `GetChannelName`)	`<CAPABILITY>_COUNT` attribute (Ex: `CHANNEL_COUNT`) `Get<Capability>Name` function (Ex: `GetChannelName`) `ACTIVE_<CAPABILITY>` attribute (Ex: `ACTIVE_CHANNEL`) `SetActive<Capability>` function (Ex: `SetActiveChannel`)

As the table shows, different methods and properties must be maintained in the IVI.NET and IVI-C hierarchies based upon the type of repeated capability. Nimbus automatically handles each case by creating the appropriate IVI-C functions and attributes.

Collection-Style Repeated Capabilities and IVI-C

The case of collection-style repeated capabilities requires special handling since this type of repeated capability is not supported by IVI-C drivers. Whenever a collection-style repeated capability is added to a driver, Nimbus treats the repeated capability as a parameter-style repeated capability in the IVI-C hierarchy. This means Nimbus automatically creates the \<CAPABILITY\>_COUNT attribute and the Get\<Capability\>Name function.

Creating IVI.NET-only and IVI-C-only Methods and Properties

There are some instances where it is not possible or desirable to expose an IVI.NET method in the IVI-C driver. Such an IVI.NET method has no associated IVI-C function and is termed an IVI.NET-only method. Correspondingly, there are occasions where an IVI-C function serves no useful purpose in the IVI.NET hierarchy. This requires IVI-C functions that have no IVI.NET counterpart — these are termed IVI-C-only functions.

IVI.NET-only methods and properties are established by deleting the linked IVI-C function or attribute.

To create an IVI.NET-only method or property

From the IVI.NET Designer, select the desired method or property.
For a method, right-click and choose Delete IVI-C Function.

For a property, right-click and choose Delete IVI-C Attribute.
The Info Panel should display None for the associated IVI-C items.

IVI-C-only functions and attributes are created by simply adding an IVI-C function or attribute directly using the IVI-C Designer. Recall that the IVI-C Designer does not push changes to the IVI.NET hierarchy, so anything created directly from the IVI-C Designer is inherently IVI-C-only.

To create an IVI-C-only function or attribute

From the IVI-C Designer, select the desired location within the IVI-C tree view.
Right-click and choose Add Function or Add Attribute.
The Info Panel shows that no IVI.NET method or property is linked with the item.