ncRead
Purpose
Read single frame from a CAN or LIN Object.
Format
| NCTYPE_STATUS | ncRead(
|
Input
ObjHandle
Object handle.
DataSize
Size of the data in bytes.
Output
DataPtr
Pointer used to return the frame.
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
ncRead reads a single frame from the object specified by ObjHandle.
DataPtr points to the variable that holds the data. Its type is undefined so that you can use the appropriate host data type. DataSize indicates the size of variable pointed to by DataPtr, and is used to verify that the size you have available is compatible with the configured read size for the object.
For information on the data type to use with DataPtr, refer to the following Network Interface and CAN Object descriptions.
You use ncRead to obtain data from the read queue of an object. Because NI-CAN handles the read queue in the background, this function does not wait for new data to arrive. To ensure that new data is available before calling ncRead, first wait for the NC_ST_READ_AVAIL state. The NC_ST_READ_AVAIL state transitions from false to true when NI-CAN places a new data item into an empty read queue, and remains true until you read the last data item from the queue.
The ncRead function is useful when you need to process one frame at a time. In order to read multiple frames, such as for bus analyzer applications, use the ncReadMult function.
When you call ncRead for an empty read queue (NC_ST_READ_AVAIL false), the data from the previous call to ncRead is returned to you again, along with the CanWarnOldData warning. If no data item has yet arrived for the read queue, a default data item is returned, which consists of all zeros.
When a new data item arrives for a full queue, NI-CAN discards the item, and the next call to ncRead returns the CanErrOverflowRead error. You can avoid this overflow behavior by setting the read queue length to zero. When a new data item arrives for a zero length queue, it simply overwrites the previous item without indicating an overflow. The NC_ST_READ_AVAIL state and CanWarnOldData warning still behave as usual, but you can ignore them if you only want the most recent data. You can use the NC_ATTR_READ_Q_LEN attribute to configure the read queue length.
CAN Network Interface Object
The data type that you use with ncRead of the Network Interface is NCTYPE_CAN_STRUCT. When calling ncRead, you should pass size of (NCTYPE_CAN_STRUCT) for the DataSize parameter.
Within the NCTYPE_CAN_STRUCT structure, the FrameType field determines the meaning of all other fields.
The following tables describe the fields of NCTYPE_CAN_STRUCT for each value of FrameType.
To determine if your hardware supports one of the following frame types for this function, refer to Frame Types for CAN and LIN Hardware.
NCTYPE_CAN_STRUCT Fields for FrameType NC_FRMTYPE_DATA (0)
| Field Name | Data Type | Description |
|---|---|---|
| FrameType | NCTYPE_UINT8 | NC_FRMTYPE_DATA (0)
This value indicates a CAN data frame. |
| ArbitrationId | NCTYPE_CAN_ARBID | Returns the arbitration ID of the received data frame.
The NCTYPE_CAN_ARBID type is an unsigned 32-bit integer that uses the bit mask NC_FL_CAN_ARBID_XTD (0x20000000) to indicate an extended ID. A standard ID (11-bit) is specified by default. The Network Interface receives data frames based on the comparators and masks configured in ncConfig (including the Series 2 Filter Mode attributes). |
| Data | Array of 8 NCTYPE_UINT8 | Returns the data bytes of the frame |
| DataLength | NCTYPE_UINT8 | Returns the number of data bytes received in the frame. This specifies the number of valid data bytes in Data. |
| Timestamp | NCTYPE_ABS_TIME | Returns the absolute timestamp when the data frame was received from the CAN network.
The timestamp data type NCTYPE_ABS_TIME is a 64-bit unsigned integer compatible with the Win32 FILETIME type. This absolute time is kept in a Coordinated Universal Time (UTC) format. UTC time is loosely defined as the current date and time of day in Greenwich, England. Microsoft defines its UTC time (FILETIME) as a 64-bit counter of 100 ns intervals that have elapsed since 12:00 a.m., January 1, 1601. Since Timestamp is compatible with Win32 FILETIME, you can pass it into the Win32 FileTimeToLocalFileTime function to convert it to the local time zone, then pass the resulting local time to the Win32 FileTimeToSystemTime function to convert to the Win32 SYSTEMTIME type. SYSTEMTIME is a struct with fields for year, month, day, and so on. For more information on Win32 time types and functions, refer to the Microsoft Win32 documentation. |
NCTYPE_FRAME_STRUCT Fields for FrameType NC_FRMTYPE_REMOTE (1)
| Field Name | Data Type | Description |
|---|---|---|
| FrameType | NCTYPE_UINT8 | NC_FRMTYPE_REMOTE (1) This value indicates a CAN remote frame. Only Series 2 hardware or later can receive remote frames using the Network Interface. For Series 1 hardware, you must handle incoming remote frames with CAN Objects only. |
| ArbitrationId | NCTYPE_CAN_ARBID | Returns the arbitration ID of the received remote frame. The NCTYPE_CAN_ARBID type is an unsigned 32-bit integer that uses the bit mask NC_FL_CAN_ARBID_XTD (0x20000000) to indicate an extended ID. A standard ID (11-bit) is specified by default. The Network Interface receives remote frames based on the comparators and masks configured in ncConfig (including the Series 2 Filter Mode attributes). |
| Data | Array of 8 NCTYPE_UINT8 | Remote frames do not contain data, so this array is empty. |
| DataLength | NCTYPE_UINT8 | Returns the Data Length Code in the remote frame. |
| Timestamp | NCTYPE_ABS_TIME | Returns the absolute timestamp when the remote frame was received from the CAN network. For information on the timestamp data type, refer to the previous table. |
NCTYPE_CAN_STRUCT Fields for FrameType NC_FRMTYPE_COMM_ERR (2)
| Field Name | Data Type | Description |
|---|---|---|
| FrameType | NCTYPE_UINT8 | NC_FRMTYPE_COMM_ERR (2)
This value indicates a logged communication warning or error as reported by the CAN hardware. This frame type occurs only when you set the Log Comm Warnings attribute to TRUE and the CAN controller is in the error passive state. Refer to ncConfig for details. For more information on CAN error handling, refer to CAN Error Detection and Confinement. |
| ArbitrationId | NCTYPE_CAN_ARBID | Indicates the type of communication problem:
8000000B hex:Comm. error: General |
| Data | Array of 8 NCTYPE_UINT8 | This field is not applicable to this frame type, and should be ignored. |
| DataLength | NCTYPE_UINT8 | This field is not applicable to this frame type, and should be ignored. |
| Timestamp | NCTYPE_ABS_TIME | Returns the absolute timestamp when the communications problem occurred.
For information on the timestamp data type, refer to the previous table. |
NCTYPE_CAN_STRUCT Fields for FrameType NC_FRMTYPE_RTSI (3)
| Field Name | Data Type | Description |
|---|---|---|
| FrameType | NCTYPE_UINT8 | NC_FRMTYPE_RTSI (3)
Indicates when a RTSI input pulse occurred relative to incoming CAN frames. This frame type occurs only when you set the RTSI Mode attribute to NC_RTSI_TIME_ON_IN (refer to ncConfig for details). |
| ArbitrationId | NCTYPE_CAN_ARBID | Returns the special value 40000001 hex. |
| Data | Array of 8 NCTYPE_UINT8 | This field is not applicable to this frame type, and should be ignored. |
| DataLength | NCTYPE_UINT8 | Returns the RTSI signal number detected. |
| Timestamp | NCTYPE_ABS_TIME | Returns the absolute timestamp when the RTSI input occurred.
For information on the timestamp data type, refer to the NCTYPE_CAN_STRUCT Fields for FrameType NC_FRMTYPE_DATA (0) table for more information. |
NCTYPE_CAN_STRUCT Fields for FrameType NC_FRMTYPE_TRIG_START (4)
| Field Name | Data Type | Description |
|---|---|---|
| IsRemote | NCTYPE_UINT8 | Value 4 specifies a start trigger frame.
When the Log Start Trigger attribute is set to 1 (True), this frame indicates the time when the start trigger occurs. For example, if you use ncConnectTerminals to connect a RTSI input to the start trigger, this frame occurs when the RTSI input pulse for the first time. Another use case for logging the start trigger would be for logging the received CAN frames in a file. This ensures that the first frame in the logfile is a start trigger frame, which specifies the absolute time (date/time) at which CAN communication started. |
| ArbitrationId | NCTYPE_CAN_ARBID | Value 0 is required. |
| Data | Array of 8 NCTYPE_UINT8 | The single data byte in the array specifies the Timestamp Format (defined in ncSetAttribute) used for all subsequent CAN frames. The value is 0 for absolute timestamps, and 1 for relative timestamps. |
| DataLength | NCTYPE_UINT8 | Value 1 is required. |
| Timestamp | NCTYPE_ABS_TIME | Absolute timestamp of the start trigger. Within a logfile, this timestamp indicates the date and time at which CAN communication started.
The format of this timestamp is always absolute, even when Data byte 0 specifies relative timestamp format. This absolute timestamp provides data/time information even when the CAN frames use the relative format. |
NCTYPE_CAN_STRUCT Fields for FrameType NC_FRMTYPE_CAN_BUS_ERROR_FRAME (6)
| Field Name | Data Type | Description |
|---|---|---|
| IsRemote | NCTYPE_UINT8 | Value 6 represents a CAN bus error frame. Refer to the NC_ATTR_LOG_BUS_ERRORS (Log Bus Errors?) attribute description for more information on CAN Bus Error frames. |
| ArbitrationId | NCTYPE_CAN_ARBID | Zero. |
| DataLength | NCTYPE_UINT8 | Four. |
| Data | Array of 8 NCTYPE_UINT8 | 0Comm State (See description below) 1—Transmit Error Counter 2—Receive Error Counter 3—ECC Register 4—X 5—X 6—X 7—X Note: X means Reserved or Don't Care. The first data byte (Comm State) indicates the current communication state of the CAN controller. The states are: 0—Error Active 1—Error Passive 2—Bus Off |
| Timestamp | NCTYPE_ABS_TIME | Time when the bus error was detected. |
NCTYPE_CAN_STRUCT Fields for FrameType NC_FRMTYPE_TRANSCEIVER_FAULT_FRAME(7)
| Field Name | Data Type | Description |
|---|---|---|
| Remote | NCTYPE_UINT8 | Value 7 represents a tranceiver fault frame. Refer to the NC_ATTR_LOG_TRANCEIVER_FAULTS (Log Tranceiver Faults?) attribute description for more information on Transceiver Fault frames. |
| ArbitrationId | NCTYPE_CAN_ARBID | Zero. |
| DataLength | NCTYPE_UINT8 | One. |
| Data | Array of 8 NCTYPE_UINT8 |
0—Transceiver fault (0=fault cleared, 1=fault present) 1—X 2—X 3—X 4—X 5—X 6—X 7—X |
| Timestamp | NCTYPE_ABS_TIME | Time when the tranceiver fault was detected. |
NCTYPE_CAN_STRUCT Fields for FrameType NC_FRMTYPE_REMOTE NC_FRMTYPE_LIN_FULL_FRAME (18)
| Field Name | Data Type | Description |
|---|---|---|
| Remote | NCTYPE_UINT8 | Value 18 represents a full frame for LIN communication. A full frame is reported when the LIN interface slave task has received one complete LIN frame. All frames for which the LIN interface slave task is a subscriber will be reported. Frames for which the LIN interface slave task is a publisher will be reported only if the NC_ATTR_SELF_RECEPTION (Self Reception) attribute is set to TRUE. |
| ArbitrationId | NCTYPE_CAN_ARBID | Zero to sixty-three. |
| DataLength | NCTYPE_UINT8 | One to eight. |
| Data | Array of 8 NCTYPE_UINT8 |
LIN frame data. |
| Timestamp | NCTYPE_ABS_TIME | Time at point of reception of LIN frame checksum. |
NCTYPE_CAN_STRUCT Fields for FrameType NC_FRMTYPE_LIN_WAKEUP_RECEIVED_FRAME (19)
| Field Name | Data Type | Description |
|---|---|---|
| Remote | NCTYPE_UINT8 | Value 19 represents a wakeup received frame for LIN communication. A wakeup received frame is reported when the LIN interface is asleep, the NC_ATTR_LIN_LOG_WAKEUP (LIN Log Wakeup) attribute is set to TRUE, and a wakeup event is detected. |
| ArbitrationId | NCTYPE_CAN_ARBID | Zero. |
| DataLength | NCTYPE_UINT8 | Zero. |
| Data | Array of 8 NCTYPE_UINT8 |
Ignored. |
| Timestamp | NCTYPE_ABS_TIME | Time at point of wakeup event detection. |
NCTYPE_CAN_STRUCT Fields for FrameType NC_FRMTYPE_LIN_BUS_INACTIVE_FRAME (20)
| Field Name | Data Type | Description |
|---|---|---|
| Remote | NCTYPE_UINT8 | Value 20 represents a bus inactive frame for LIN communication. Bus inactive detection begins when the LIN interface senses the first activity on the bus. When activity ceases, a bus inactive frame is reported if the inactivity lasts for more than four seconds. |
| ArbitrationId | NCTYPE_CAN_ARBID | Zero. |
| DataLength | NCTYPE_UINT8 | Zero. |
| Data | Array of 8 NCTYPE_UINT8 |
Ignored. |
| Timestamp | NCTYPE_ABS_TIME | Time at point of four second timeout. |
NCTYPE_CAN_STRUCT Fields for FrameType NC_FRMTYPE_LIN_BUS_ERROR_FRAME (21)
| Field Name | Data Type | Description |
|---|---|---|
| IsRemote | NCTYPE_UINT8 | Value 21 represents a LIN bus error frame for LIN communication. A LIN bus error frame is reported when the NC_ATTR_LOG_BUS_ERRORS (Log Bus Errors?) attribute is set to TRUE, and a bus error occurs. |
| ArbitrationId | NCTYPE_CAN_ARBID | Zero. |
| DataLength | NCTYPE_UINT8 | Varies depending on the error. Refer to the LIN Bus Errors and Descriptions table, in ncSetAttribute for information. |
| Data | Array of 8 NCTYPE_UINT8 |
Error frame information. |
| Timestamp | NCTYPE_ABS_TIME | Time at point of bus error detection. |
Error Active, Error Passive, and Bus Off States
When the CAN communication controller transfers into the error passive state, NI-CAN returns the warning CanCommWarning from read functions.
When the transmit error counter of the CAN communication controller increments above 255, the network interface transfers into the bus off state as dictated by the CAN protocol. The network interface stops communication so that you can correct the defect in the network, such as a malfunctioning cable or device. When bus off occurs, NI-CAN returns the CanErrComm error code.
If no CAN devices are connected to the network interface port, and you attempt to transmit a frame, the CanWarnComm status occurs. This warning occurs because the missing acknowledgment bit increments the transmit error counter until the network interface reaches the error passive state, but bus off state is never reached.
For more information about transceiver fault handling, refer to the description of the NC_ATTR_LOG_COMM_ERRS attribute ID in the ncConfig function description.
CAN Object
The data type that you use with ncRead of the CAN Object is NCTYPE_CAN_DATA_TIMED. When calling ncRead, you should pass size of (NCTYPE_CAN_DATA_TIMED) for the DataSize parameter. The following table describes the fields of NCTYPE_CAN_DATA_TIMED.
NCTYPE_CAN_DATA_TIMED Field Names
| Field Name | Data Type | Description |
|---|---|---|
| Data | Array of 8 NCTYPE_UINT | Data array returns 8 data bytes. The actual number of valid data bytes depends on the CAN Object configuration specified in ncConfig.
If the CAN Object Communication Type specifies Transmit, data frames are transmitted, not received, so Data is ignored. For this Communication Type, the ncRead function has no effect. If the CAN Object Communication Type specifies Receive, Data always contains Data Length valid bytes, where Data Length was configured using ncConfig. |
| Timestamp | NCTYPE_ABS_TIME | Returns the absolute timestamp value. The timestamp data type NCTYPE_ABS_TIME is a 64-bit unsigned integer compatible with the Win32 FILETIME type. This absolute time is kept in a Coordinated Universal Time (UTC) format. UTC time is loosely defined as the current date and time of day in Greenwich, England. Microsoft defines its UTC time (FILETIME) as a 64-bit counter of 100 ns intervals that have elapsed since 12:00 a.m., January 1, 1601.
Since Timestamp is compatible with Win32 FILETIME, you can pass it into the Win32 FileTimeToLocalFileTime function to convert it to the local time zone, then pass the resulting local time to the Win32 FileTimeToSystemTime function to convert to the Win32 SYSTEMTIME type. SYSTEMTIME is a struct with fields for year, month, day, and so on. For more information on Win32 time types and functions, refer to the Microsoft Win32 documentation. |