ibInstallCallback

int ibInstallCallback (int boardOrDevice, int eventMask, GPIBCallbackPtr callbackFunction, void *callbackData);

Purpose

Allows you to install a synchronous callback function for a specified interface or device. If you want to install an asynchronous callback, use ibnotify instead.

The callback function is called when any of the GPIB events you specify in eventMask have occurred on the interface or device, but only while you allow the system to process events. The system can process events when you call ProcessSystemEvents or GetUserEvent, or when you call RunUserInterface and none of your callback functions are currently active. The callbacks are called “synchronous” because you can invoke them only in the context of normal event processing.

Unlike asynchronous callbacks, there are no multithreading issues in an synchronous callback. On the other hand, the latency between the occurrence of a GPIB event and the invocation of the callback function is greater and more unbounded with synchronous callbacks than with asynchronous callbacks.

You can install only one callback function for each interface or device. Each call to ibInstallCallback for the same interface or device supersedes the previous call.

To disable callbacks for an interface or device, pass 0 for eventMask.

You must have version 1.2 or later of the NI-488.2M driver to use ibInstallCallback.

Parameters

Input
Name Type Description
boardOrDevice integer
Board index, or board or device descriptor you obtain from OpenDev, ibfind, or ibdev.
eventMask integer
Specifies the events upon which the callback function is called. Pass 0 to disable callbacks. Refer to the following Parameter Discussion.
callbackFunction GPIBCallbackPtr Name of the user function to call when the specified events occur. Refer to the following Parameter Discussion.
callbackData void pointer Pointer to a user-defined, 4-byte value to pass to the callback function.

Return Value

Name Type Description
status integer
Same value as the ibsta status variable. Refer to your NI-488.2 or NI-488.2M user manual for a description of the values of ibsta.

Parameter Discussion

eventMask

You specify the conditions upon which LabWindows/CVI invokes the callback function as bits in eventMask. The bits correspond to the bits of the ibsta status word. This value reflects a sum of one or more events. If any one of the conditions occur, the callback is called.

If, when you install the callback, one of the bits you set in the mask is already TRUE, LabWindows/CVI invokes the callback immediately. For example, if you pass CMPL as the eventMask, and ibwait would currently return a status word with CMPL set, LabWindows/CVI calls the callback immediately.

The following mask bits are valid:

SRQI, RQS, and Auto Serial Polling

If you want to install a callback for the SRQI (board-level) event, you must disable autopolling. You can disable autopolling with the following function call:

ibconfig (boardIndex, IbcAUTOPOLL, 0);

If you want to install a callback for the RQS (device-level) event, you must enable autopolling for the board. You can enable autopolling with the following function call:

ibconfig (boardIndex, IbcAUTOPOLL, 1);

callbackFunction

The callback function must have the following form:

void CallbackFunctionName (int boardOrDevice, int mask, void *callbackData);

mask and callbackData are the same values you pass to ibInstallCallback.

If invoked because of an SRQI or RQS condition, the callback function must call ibrsp to read the status byte. For an SRQI (board-level) condition, calling the ibrsp function is necessary to cause the requesting device to turn off the SRQ line.

char statusByte;
ibrsp (device, &statusByte);

If invoked because of a completed asynchronous I/O operation that ibrda, ibwrta, or ibcmda started, the callback function must make the following call:

ibwait (boardOrDevice, TIMO | CMPL);

The ibcnt and ibcntl status variables are not updated until you call ibwait.

See Also

ibnotify