Continuously reads the discrete inputs until a change occurs.
- Parameters
-
[in] | handle | Valid handle returned by SM_Open(). |
[in] | start | Modbus address to begin the read (zero-indexed). |
[in] | number | Quantity of inputs to read. |
[out] | values | On input change, this buffer will be populated with the input state. |
[in] | delay | Time to delay between issuing reads (ms). |
[in] | blocking | Indicates whether to wait for a change (non-zero), or immediately return control to the caller (zero). |
- Return values
-
1 | Input state has changed. 'Values' parameter now contains valid input state. (Blocking mode only) |
0 | Successful completion. |
-1 | Invalid SeaMAX handle. |
-2 | There is already a pending NotifyOnInputChange request. See SM_NotifyInputState() to determine it's state or to cancel it. |
-10 | Could not read inputs. Parameters may be incorrect or the device may not be reachable, present, or may be busy. |
SM_NotifyOnInputChange will continuously read the inputs until a change is detected, similar to consecutive SM_ReadDigitalInputs() calls. The delay between reads is configurable based on the delay parameter. After an input change, the values parameter will be populated with the current input state.
- Note
- Only one notify request can be outstanding at a time. SM_ReadDigitalInputs() has more information on parameter values.
There are two modes of operation for this function: blocking and non-blocking. If the blocking parameter is supplied as non-zero, SM_NotifyOnInputChange will not return until a input change occurs.
Since blocking mode may be dangerous in instances where a logic change can not be guaranteed, a non-blocking notify request may be issued that will begin reading the inputs and terminate once canceled or a change occurs. Execution returns immediately to the caller, whereby the SM_NotifyInputState() function provides an interface to cancel the request or check on it's status.
- Note
- See the SM_NotifyInputState() function for more information on cancelling or checking the status of an outstanding request.
- Warning
- The 'values' parameter should be pre-allocated with enough bytes of space to hold 'number' bits of input states. For instance, if 12 inputs are being read, the values parameter should have 2 bytes of space allocated before calling this function.
-
The 'values' parameter should not be accessed (read or written) until SM_NotifyInputState() indicates that the request has completed (either canceled by the user or completed due to input change). Accessing the values buffer may prevent the notify request from completing, resulting in data loss.
- See also
- SM_NotifyInputState()