Adding Callback Functions

The IVI specifications define a mechanism for a driver to invoke a function on client code in response to some event within the driver. Such a function is referred to as a callback function. Unlike other functions created with the Nimbus Driver Designer, callback functions are implemented by the client. The driver only provides the function signature in the driver header file and the client must take care to implement the callback function using that exact signature.

Adding a callback function to a driver results in code such as the following being added to the driver's header file:

C++

Copy

/*- Callback Functions */

#ifdef IVI_INSTR_CALLBACKS

typedef ViBoolean (_VI_FUNCH * acme_ReadHandler) (ViReal64 Data[]);

ViStatus _VI_FUNC acme_ReadWaveformData(ViSession Vi, acme_ReadHandler Handler);

#endif

In the above code, the typedef specifies a callback function that accepts an array of ViReal64 as an input parameter and returns a ViBoolean.

The ReadWaveformData function above accepts a ReadHandler callback as an input parameter. The semantics of how and when the driver invokes the client's callback function is completely driver defined, as is the thread on which the client may receive the callback.

To add a callback function

From Solution Explorer, double-click the Driver Designer node under the Nimbus node.
The IVI-C Driver Designer tree view opens.
Right-click on the Callbacks node and select Add Callback Function.
A new callback function is added with a default name and a void return type, and the tree node enters edit mode.

With the callback function node still in edit mode, type the desired name and return type of the callback function and hit the Enter key.

Note
Unlike normal IVI-C driver functions which must always return ViStatus, callback functions can be defined to return any IVI-C data type (other than another callback function).

After the callback function is added, the IVI-C Callback Function General Editor appears in the right portion of the IVI-C Driver Designer. See the help topic for that Item Editor for details on defining the function further.
Once a function has been added, parameters can be added to the callback function in the same fashion as normal IVI-C driver functions. Notably, callback functions cannot have parameters that are themselves callback functions.