ncReadMult
Purpose
Read multiple frames from a CAN or LIN Object.
Format
| NCTYPE_STATUS | ncReadMult(
|
Input
ObjHandle
Object handle.
DataSize
The size of the data buffer in bytes.
DataPtr
Points to data buffer in which the data returned.
Output
ActualDataSize
The number of bytes actually returned.
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
This function returns multiple frames from the read queue of the object specified by ObjHandle. When used with the Network Interface, ncReadMult is useful in analyzer applications where data frames need to be acquired at a High-Speed and stored for analysis in the future. For single frame and most recent data frame acquisition, you should use ncRead.
DataPtr points to an array of either NCTYPE_CAN_STRUCT or NCTYPE_CAN_DATA_TIMED. DataSize indicates the size of the array pointed to by DataPtr (in bytes). This size is specified in bytes in order to verify that the proper data type and alignment is used. When ncReadMult returns, the number of bytes copied into DataPtr is provided in ActualDataSize.
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 ncReadMult, first wait for the NC_ST_READ_MULT state. Refer to NC_ST_READ_MULT (00000008 hex) in the ncCreateNotification function description for more information on this state.
Unlike the ncRead function, the ncReadMult function does not return the CanWarnOldData warning to indicate zero frames. If there is no new data, the function returns with an ActualDataSize of zero.
The description for CanErrOverflowRead and the host data types is identical to that of ncRead with the exception of CanWarnOldData, described above.
Refer to the ncRead function description for more details on the structures used with ncReadMult.