nctReadTimestamped

Purpose

Reads samples from a CAN task initialized with Mode of nctModeTimestampedInput. For an overview of nctReadTimestamped, refer to the Read Timestamped section of Using the Channel API.

Format

Inputs

TaskRef

Task reference from the previous NI-CAN function. The task reference is originally returned from nctInitStart, nctInitialize, or nctCreateMessage.

The Mode initialized for the task must be NctModeTimestampedInput.

NumberOfSamplesToRead

Specifies the number of samples to read for the task.

Outputs

TimestampArray

Returns the time at which each corresponding sample in SampleArray was received in a CAN message.

The timestamps are returned as an array of arrays (2D array), one array for each channel initialized in the task. The array of each channel must have NumberOfSamplesToRead entries allocated.

For example, if you call nctInitStart with ChannelList of mych1,mych2, then call nctReadTimestamped with NumberOfSamplesToRead of 20, both TimestampArray and SampleArray must be allocated as:

nctTypeTimestamp TimestampArray[2][20];

f64 SampleArray[2][20];

The order of channel entries in TimestampArray is the same as the order in the original ChannelList.

If you need to determine the number of channels in the task after initialization, get the nctPropNumChannels property for the task reference.

Each timestamp in TimestampArray uses the nctTypeTimestamp data type. The nctTypeTimestamp data type is a 64-bit unsigned integer compatible with the Microsoft 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. Because nctTypeTimestamp is compatible with Win32 FILETIME, you can pass it into the Win32 FileTimeToLocalFileTime function to convert it to the local time zone, and 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.

SampleArray

Returns the sample value(s) for each received CAN message.

The samples are returned as an array of arrays (2D array), one array for each channel initialized in the task. The array of each channel must have NumberOfSamplesToRead entries allocated.

You must allocate SampleArray exactly as TimestampArray, and the order of channel entries is the same for both.

NumberOfSamplesReturned

Indicates the number of samples returned for each channel in SampleArray, and the number of timestamps returned for each channel in TimestampArray. The remaining entries are left unchanged (zero).

Return Value

The return value indicates the function call status as a signed 32-bit integer. Zero means the function executed successfully. A negative value specifies an error, which means the function did not perform the expected behavior. A positive value specifies a warning, which means the function performed as expected, but a condition arose that may require attention.

Use the ncStatusToString function of the Frame API to obtain a descriptive string for the return value. The ncStatusToString and ncGetHardwareInfo functions are the only Frame API functions that can be called within a Channel API application.

Description

Each returned sample corresponds to a received CAN message for the channels initialized in ChannelList. For each sample, nctReadTimestamped returns the sample value and a timestamp that indicates when the message was received.

When using Mode of nctModeTimestampedInput, you cannot specify channels in ChannelList that span multiple messages.

Because the timing of samples returned by nctReadTimestamped is determined by when the message is received, the initialized SampleRate is not used.

The nctPropTimeout property determines whether this function waits for the NumberOfSamplesToRead messages to arrive from the network. The default value of nctPropTimeout is zero, but you can change it using the nctSetProperty function.

If nctPropTimeout is greater than zero, the function will wait for NumberOfSamplesToRead messages to arrive. If NumberOfSamplesToRead messages are not received before thenctPropTimeout expires, an error is returned.

If nctPropTimeout is zero, the function does not wait for messages, but instead returns samples from the messages received since the previous call to nctReadTimestamped. The number of samples returned is indicated in the NumberOfSamplesReturned output, up to a maximum of NumberOfSamplesToRead messages. If no new message has been received, NumberOfSamplesReturned is 0, and the return value indicates success.