ncCreateNotification

Purpose

Create a notification call back for an object.

Format

Input

ObjHandle

Object handle. The ncCreateNotification function is not supported by the 847x and 847x with Sync series CAN and LIN interfaces.

DesiredState

States for which notification is sent.

Timeout

Length of time to wait in milliseconds.

RefData

Pointer to user-specified reference data.

Callback

Address of the callback function.

Output

Return Value

Status of the function call, returned as a signed 32-bit integer. Zero means the function executed successfully. Negative specifies an error, meaning the function did not perform expected behavior. Positive specifies a warning, meaning the function performed as expected, but a condition arose that might require attention. For more information, refer to ncStatusToString.

Description

ncCreateNotification creates a notification callback for the object specified by ObjHandle. The NI-CAN driver uses the notification callback to communicate state changes to the application.

This function is normally used when you want to allow other code to execute while waiting for NI-CAN states, especially when the other code does not call NI-CAN functions. If such background execution is not needed, the ncWaitForState function offers better overall performance. The ncWaitForState function cannot be used at the same time as ncCreateNotification.

The functions ncWaitForState and ncCreateNotification use the same underlying implementation. Therefore, for each object handle, only one of these functions can be pending at a time. For example, you cannot invoke ncWaitForState or ncCreateNotification twice from different threads for the same object. For different object handles, these functions can overlap in execution.

This function is not supported for Visual Basic 6.

Upon successful return from ncCreateNotification, the notification callback is invoked whenever one of the states specified by DesiredState occurs in the object, or if an error occurs in the object. If DesiredState is zero, notifications are disabled for the object specified by ObjHandle. DesiredState specifies a bit mask for which notification is desired. You can use a single state alone, or you can OR them together.

NC_ST_READ_AVAIL (00000001 hex)

At least one frame is available, which you can obtain using an appropriate read function.

The state is set whenever a frame arrives for the object. The state is cleared when the read queue is empty.

NC_ST_READ_MULT (00000008 hex)

A specified number of frames are available, which you can obtain using ncReadMult. The number of frames is one half the Read Queue Length by default, but you can change it using the ReadMult Size for Notification attribute of ncSetAttribute.

The state is set whenever the specified number of frames are stored in the read queue of the object. The state is cleared when you call the read function, and less than the specified number of frames exist in the read queue.

NC_ST_REMOTE_WAKEUP (00000040 hex, Remote Wakeup)

Remote wakeup occurred, and Transceiver Mode (NC_ATTR_TRANSCEIVER_MODE) has changed from Sleep to Normal. For more information on remote wakeup, refer to NC_ATTR_TRANSCEIVER_MODE.

This state is set when a remote wakeup occurs (end of wakeup frame). This state is not set when the application changes Transceiver Mode from Sleep to Normal (local wakeup).

This state is cleared when:

• You open the Network Interface, such as when the application begins.

• You stop the Network Interface.

• You set the Transceiver Mode, such as each time you set Sleep mode.

For as long as this state is true, the transceiver mode is Normal. The transceiver mode also can be Normal when this state is false, such as when you perform a local wakeup.

NC_ST_WRITE_MULT (00000080 hex)

The state is set whenever there is free space in the write queue to accept at least 512 frames to write. The state is cleared when you call the ncWrite or ncWriteMult function, and less than 512 frames can be accepted to write in the write queue.

This state is valid only on the Network Interface.

NC_ST_WRITE_SUCCESS (00000002 hex)

All frames provided with a write function have been successfully transmitted onto the network. Successful transmit means that the frame won arbitration, and was acknowledged by a remote device.

The state is set when the last frame in the write queue is transmitted successfully. The state is cleared when a write function is called.

When communication starts, the NC_ST_WRITE_SUCCESS state is true by default.

For CAN Objects, Write Success does not always mean that transmission has stopped. For example, if a CAN Object is configured for Transmit Data Periodically, Write Success occurs when the write queue has been emptied, but periodic transmit of the last frame continues.

The NI-CAN driver waits up to Timeout for one of the bits set in DesiredState to become set in the attribute NC_ATTR_STATE. You can use the special Timeout value NC_DURATION_INFINITE to wait indefinitely.

The Callback parameter provides the address of a callback function in the application. Within the Callback function, you can call any of the NI-CAN functions except ncCreateNotification and ncWaitForState.

With the RefData parameter, you provide a pointer that is sent to all notifications for the given object. This pointer normally provides reference data for use within the Callback function. For example, when you create a notification for the NC_ST_READ_AVAIL state, RefData is often the data pointer that you pass to ncRead to read available data. If the callback function does not need reference data, you can set RefData to NULL.

Callback Prototype

Callback Parameters

ObjHandle

Object handle.

State

Current state of object.

Status

Object status.

RefData

Pointer to the reference data.

Callback Return Value

The value you return from the callback indicates the desired states to re-enable for notification. If you no longer want to receive notifications for the callback, return a value of zero.

If you return a state from the callback, and that state is still set in the NC_ATTR_STATE attribute, the callback is invoked again immediately after it returns. For example, if you return NC_ST_READ_AVAIL when the read queue has not been emptied, the callback is invoked again.

Callback Description

In the prototype for Callback, _NCFUNC_ ensures a proper calling scheme between the NI-CAN driver and the callback.

The Callback function executes in a separate thread in the process. Therefore, it has access to any process global data, but not to thread local data. If the callback needs to access global data, you must protect that access using synchronization primitives (such as semaphores), because the callback is running in a different thread context. Alternatively, you can avoid the issue of data protection entirely if the callback simply posts a message to the application using the Win32 PostMessage function. For complete information on multithreading issues, refer to the Win32 Software Development Kit (SDK) online help.

In LabWindows/CVI, you cannot access User Interface library functions within the callback thread. To defer a callback for User Interface interaction, use the CVI PostDeferredCall function. For more information, refer to the LabWindows/CVI documentation.

The ObjHandle is the same object handle passed to ncCreateNotification. It identifies the object generating the notification, which is useful when you use the same callback function for notifications from multiple objects.

The State parameter holds the current state(s) of the object that generated the notification (NC_ATTR_STATE attribute). If the Timeout passed to ncCreateNotification expires before the desired states occur, or if any other error occurs in the object, the NI-CAN driver invokes the callback with State equal to zero.

The Status parameter holds the current status of the object. If an error occurs, State is zero and Status holds the error status. The most common notification error occurs when the Timeout passed to ncCreateNotification expires before the desired states occur (CanErrFunctionTimeout status code). If no error is reported, Status is CanSuccess.

The RefData parameter is the same pointer passed to ncCreateNotification, and it accesses reference data for the Callback function.