ncWaitForState

Purpose

Wait for one or more states to occur in an object.

Format

Input

ObjHandle

Object handle.

DesiredState

States for which to wait.

Timeout

Length of time to wait in milliseconds.

Output

StatePtr

Current state of object when desired states occur. The state is returned to you using the pointer StatePtr.

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

You use ncWaitforState to wait for one or more states to occur in the object specified by ObjHandle.

This function 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 (FFFFFFFF hex) to wait indefinitely.

DesiredState specifies a bit mask of states for which the wait should return. 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.

This state applies only to Series 1 and Series 2 hardware.

NC_ST_REMOTE_WAKEUP (00000040 hex)

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 through 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, write success means that the frame won arbitration, and was acknowledged by a remote device. For LIN, write success means that the frame was successfully processed by the LIN interface.

When the states in DesiredState are detected, the function returns the current value of the NC_ATTR_STATE attribute. If an error occurs, the function returns immediately, and the state returned is zero.

While waiting for the desired states, ncWaitForState suspends the current thread execution. Other Win32 threads in the application can still execute.

If you want to allow other code in the application to execute while waiting for NI-CAN states, refer to the ncCreateNotification function.

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 twice from different threads for the same object. For different object handles, these functions can overlap in execution.