# ibnotify

int ibnotify (int boardOrDevice, int eventMask, GpibNotifyCallback_t callbackFunction, void *callbackData);

## Purpose

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

LabWindows/CVI calls the callback function when any of the GPIB events you specify in eventMask occur on the specified interface or device. LabWindows/CVI can call asynchronous callbacks at any time while your program is running. You do not have to allow the system to process events. Because the callback is called in another thread, you must protect any data that is shared by the callback and your main program. Refer to the Operations in Asynchronous Callbacks section.

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

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

## 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 | GpibNotifyCallback_t | Name of the function LabWindows/CVI calls 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.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.

At the board level, you can specify any of the status word bits that you can specify in the waitMask parameter to ibwait for a board, other than ERR. This includes SRQI, END, CMPL, TIMO, CIC, and others.

At the device level, you can specify any of the status word bits that you can specify in the waitMask parameter to ibwait for a device, other than ERR. This includes RQS, END, CMPL, and TIMO.

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 __stdcall CallbackFunctionName (int boardOrDevice, int sta, int err, long cntl, void *callbackData);

callbackData is the same callbackData value you pass to ibnotify. sta, err, and cntl contain the information that you normally obtain using the ibsta, iberr, and ibcntl global variables or ThreadIbsta, ThreadIberr, and ThreadIbcntl. The global variables and thread status functions return undefined values within the callback function. So you must use sta, err and cntl instead.

The value you return from the callback function is very important. It is the event mask that is used to rearm the callback. Returning 0 disarms the callback; that is, it is not called again until you make another call to ibnotify. If you return an event mask different than the one you originally passed to ibnotify, ibnotify uses the new event mask. Normally, you want to return the same event mask that you originally passed to ibnotify.

If you return an invalid event mask or if there is an operating system error in rearming the callback, the callback is called with the sta set to ERR, err set to EDVR, and cntl set to IBNOTIFY_REARM_FAILED.

| Caution Because the callback can be called as the result of a rearming error, you should always check the value of the sta parameter to make sure that one of the requested events has in fact occurred.

If invoked because of an SRQI or RQS condition, the callback function should call ibrsp to read the status byte. For an SRQI (board-level) condition, calling ibrsp 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.

Operations in Asynchronous Callbacks

Asynchronous callbacks can be called at any time while your program is running. You do not have to allow the system to process events. Because the callback is called in another thread, you must protect any data that is shared by the callback and your main program. You must not call ibnotify or ibInstallCallback from the callback.

If you need to do perform operations that are not thread safe or perform operations that must be done in your main application thread, you can do the following:

1. In your asynchronous callback,

- Perform the time-critical operations
- Call PostDeferredCall to schedule a synchronous callback.

2. In the synchronous callback, perform the rest of the operations.

## See Also

ibInstallCallback