ncWaitForState (Wait For State)
Purpose
Wait for one or more states to occur in an object.
Format
LabVIEW
C
| NCTYPE_STATUS | ncWaitForState(
NCTYPE_OBJH ObjHandle,
NCTYPE_STATE DesiredState,
NCTYPE_DURATION Timeout,
NCTYPE_STATE_P CurrentState) |
Input
| ObjHandle | Object handle of an open Explicit Messaging Object or an I/O Object |
| DesiredState | States to wait for |
| Timeout | Number of milliseconds to wait for one of the desired states |
Output
| CurrentState | Current state of object |
Function Description
Use ncWaitforState to wait for one or more states to occur in the object specified by ObjHandle.
ncWaitforState is commonly used to wait for the Established state of an Explicit Messaging Object, or else to wait for an explicit message response resulting from a call to ncWriteDnetExplMsg, then read that response using ncReadDnetExplMsg.
While waiting for the desired states, ncWaitForState suspends the current execution. For C, this could suspend your front panel user interface. For LabVIEW, you can still access your front panel and the functions that are not directly connected to ncWaitForState can still execute. If you want to allow other code in your application to execute while waiting for NI-DNET states, refer to the ncCreateNotification (C only) 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.
The status returned from ncWaitForState indicates any error detected by NI-DNET. You should always check this return status prior to checking the CurrentState value returned from ncWaitForState.
Parameter Descriptions
ObjHandle
| Description | ObjHandle must contain an object handle returned from ncOpenDnetExplMsg or ncOpenDnetIO. In LabVIEW, ObjHandle passes through the VI as an output so that it can be used for subsequent function calls for the object. |
| Values | The encoding of ObjHandle is internal to NI-DNET. |
DesiredState
| Description | States to wait for. Each state is represented by a single bit so that you can wait for multiple states simultaneously. For example, if NI-DNET provides states with values of hex 1 and hex 4, DesiredState of hex 5 waits for either state to occur. ReadAvail for the I/O Object For the I/O Object, the ReadAvail state is set when a new input message is received from the network. The ReadAvail state clears when you call ncReadDnetIO. For example, for a change-of-state (COS) I/O connection, the ReadAvail state sets when a COS input message is received. Although you can use ncWaitForState with an I/O Object, it is often preferable to use a notification (ncCreateNotification, C only). Use of a notification callback for the ReadAvail state allows your application to handle multiple I/O connections independently. ReadAvail for the Explicit Messaging ObjectFor the Explicit Messaging Object, the ReadAvail state sets when an explicit message response is received from the network. The ReadAvail state clears when you call ncReadDnetExplMsg. An explicit message response is received only after you send an explicit message request using ncWriteDnetExplMsg. The following sequence of calls is typical: ncWriteDnetExplMsg, ncWaitForState, ncReadDnetExplMsg. This sequence is used internally by ncGetDnetAttribute and ncSetDnetAttribute. The ReadAvail state is not needed when using the explicit messaging functions ncGetDnetAttribute and ncSetDnetAttribute because both of these functions wait for the explicit message response internally. Established for the Explicit Messaging ObjectFor the Explicit Messaging Object, the Established state is clear (not established) before you start communication using ncOperateDnetIntf. After you start communication, the Established state remains clear until the explicit message connection has been successfully established with the remote DeviceNet device. After the explicit message connection has been established, the Established state sets and remains set for as long as the explicit message connection is open. Until the Established state sets for the Explicit Messaging Object, all calls to ncGetDnetAttribute, ncSetDnetAttribute, or ncWriteDnetExplMsg return the error CanErrNotStarted. Before you call any of these functions in your application, you must first wait for the Established state to set. After the Established state is set, unless communication problems occur with the device (CanErrFunctionTimeout), it remains set until you stop communication using ncOperateDnetIntf. While waiting for one of the above states, if an error occurs (such as a communication error or an initialization error), the wait returns immediately with the appropriate error code. For example, if you call ncWaitforState with DesiredState of ReadAvail, the wait function will return when data is available for a read, or when a DeviceNet communication error (such as connection timeout) is detected. |
| Values | A combination of one or more of the following bit values. 1 hex (ReadAvail, constant NC_ST_READ_AVAIL) 8 hex (Established, constant NC_ST_ESTABLISHED) In LabVIEW and the LabWindows/CVI function panel, to facilitate combining multiple states, you can select a valid combination from an enumerated list of all valid combinations. This list contains the names of each state in the combination, such as ReadAvail or Established. |
Timeout
| Description | Number of milliseconds to wait for one of the desired states. If the timeout expires before one of the desired states occurs, ncWaitForState returns a status of BFF62001 hex (CanErrFunctionTimeout). The special timeout value of FFFFFFFF hex is used to wait indefinitely. |
| Values | 1 to 200000 or FFFFFFFF hex (infinite duration, constant NC_DURATION_INFINITE) |
CurrentState
| Description | Current state of the object. If one of the desired states occurs, it provides the current value of the ReadAvail and Established states. If the Timeout expires before one of the desired states occurs, it has the value 0. |
| Values | 0 (desired states did not occur) or A combination of one or more of the following bit values. 1 hex (ReadAvail, constant NC_ST_READ_AVAIL) 8 hex (Established, constant NC_ST_ESTABLISHED) |
Examples
LabVIEW
Wait up to 10 seconds for the ReadAvail state of an Explicit Messaging Object.
C
Wait up to 10 seconds for the ReadAvail state of the Explicit Messaging Object referenced by objh.
NCTYPE_STATUS status;
NCTYPE_OBJH objh;
NCTYPE_STATE currstate;
status = ncWaitForState(objh, NC_ST_READ_AVAIL, 10000, &currstate);