JLS Reader#

group Reader

JLS reader.

Typedefs

typedef int32_t (*jls_rd_annotation_cbk_fn)(void *user_data, const struct jls_annotation_s *annotation)#

The function called for each annotation.

See also

jls_rd_annotations

Param user_data:

The arbitrary user data.

Param annotation:

The annotation which only remains valid for the duration of the call. It points into the reader’s internal buffer, so any reader call made from within the callback also invalidates it. Copy what you need first.

Return:

0 to continue iteration or any other value to stop.

typedef int32_t (*jls_rd_user_data_cbk_fn)(void *user_data, uint16_t chunk_meta, enum jls_storage_type_e storage_type, uint8_t *data, uint32_t data_size)#

The function called for each user data entry.

See also

jls_rd_user_data

Param user_data:

The arbitrary user data.

Param chunk_meta:

The chunk meta value.

Param storage_type:

The data storage type.

Param data:

The data, which only remains valid for the duration of the call. It points into the reader’s internal buffer, so any reader call made from within the callback also invalidates it. Copy what you need first.

Param data_size:

The size of data in bytes.

Return:

0 to continue iteration or any other value to stop.

typedef int32_t (*jls_rd_utc_cbk_fn)(void *user_data, const struct jls_utc_summary_entry_s *utc, uint32_t size)#

The function called for each UTC entry.

See also

jls_rd_annotations

Param user_data:

The arbitrary user data.

Param utc:

The array of utc entries, which are sample_id / timestamp pairs. The array only remains valid for the duration of the call. It may point into the reader’s internal buffer, so any reader call made from within the callback also invalidates it.

Param size:

The number of utc entries for this callback.

Return:

0 to continue iteration or any other value to stop.

Functions

int32_t jls_rd_open(struct jls_rd_s **instance, const char *path)#

Open a JLS file to read contents.

Call jls_rd_close() when done.

Parameters:

  • instance – [out] The new JLS read instance.

  • path – The JLS file path.

Returns:

0 or error code.

void jls_rd_close(struct jls_rd_s *self)#

Close a JLS file opened with jls_rd_open().

Parameters:

self – The JLS read instance.

int32_t jls_rd_sources(struct jls_rd_s *self, struct jls_source_def_s **sources, uint16_t *count)#

Get the array of sources in the file.

Parameters:

  • self – The reader instance.

  • sources – [out] The array of sources.

  • count – [out] The number of items in sources.

Returns:

0 or error code.

int32_t jls_rd_signals(struct jls_rd_s *self, struct jls_signal_def_s **signals, uint16_t *count)#

Get the array of signals in the file.

Parameters:

  • self – The reader instance.

  • signals – [out] The array of signals.

  • count – [out] The number of items in signals.

Returns:

0 or error code.

int32_t jls_rd_signal(struct jls_rd_s *self, uint16_t signal_id, struct jls_signal_def_s *signal)#

Get the signal by signal_id.

Parameters:

  • self – The reader instance.

  • signal_id – The signal id to get.

  • signal – [out] The signal definition.

Returns:

0 or error code.

int32_t jls_rd_fsr_length(struct jls_rd_s *self, uint16_t signal_id, int64_t *samples)#

Get the number of samples in an FSR signal.

Parameters:

  • self – The reader instance.

  • signal_id – The signal id.

  • samples – [out] The number of samples in the signal.

Returns:

0 or error code.

int32_t jls_rd_fsr(struct jls_rd_s *self, uint16_t signal_id, int64_t start_sample_id, void *data, int64_t data_length)#

Read fixed sample rate (FSR) data.

Parameters:

  • self – The reader instance.

  • signal_id – The signal id. The first recorded sample is always 0. To get the first recorded sample_id, see jls_signal_def_s.sample_id_offset.

  • start_sample_id – The starting sample id to read.

  • data – [out] The samples read.

  • data_length – The number of samples to read. data is at least this many samples. For data types less than 8 bits long, you need to provide an extra byte to allow for data shifting. Therefore data is at least 1 + (data_length * entry_size_bits) / 8 bytes.

Returns:

0 or error code

int32_t jls_rd_fsr_f32(struct jls_rd_s *self, uint16_t signal_id, int64_t start_sample_id, float *data, int64_t data_length)#

Read fixed sample rate (FSR) float32 data.

Parameters:

  • self – The reader instance.

  • signal_id – The signal id. The first recorded sample is always 0. To get the first recorded sample_id, see jls_signal_def_s.sample_id_offset.

  • start_sample_id – The starting sample id to read.

  • data – [out] The samples read.

  • data_length – The number of samples to read. data is also at least this many entries (4 * data_length bytes).

Returns:

0 or error code

int32_t jls_rd_fsr_statistics(struct jls_rd_s *self, uint16_t signal_id, int64_t start_sample_id, int64_t increment, double *data, int64_t data_length)#

Read the statistics data for a fixed sampling rate signal.

Non-finite samples (NaN, +/-inf) are ignored, matching the summaries the writer computes. A window without any finite sample reports NaN for all four statistics. Integer signals with a fixed-point q scale each sample by 2^-q, see JLS_DATATYPE_DEF.

The reported std is the sample standard deviation (n - 1 divisor) whether computed from samples or from summaries.

Summary entries do not record their finite sample count. When statistics use summaries, an entry that contains some non-finite samples contributes with the weight of its full sample count.

For data_length 1, a window shorter than 25 * sample_decimate_factor samples is computed from the samples, so its statistics are sample-accurate. A longer window computes its partial first and last summary entries from the samples and combines the stored summary entries between them. Its min and max are exact. Its mean and std are accurate to the summary precision: summaries store float64 for f64, u32, u64, i32, and i64 data and float32 for all other types, which limits the std of a signal whose mean is large relative to its std (about 2e-5 relative for 15 V with a 4 mV std). Entries with some non-finite samples contribute their full count, as above.

For larger data_lengths, the external boundaries for start and end are computed as for data_length 1. The internal boundaries are approximated, perfect for waveform display, but perhaps not suitable for other use cases. For sample-accurate statistics over a long window, read the samples with jls_rd_fsr() and compute them.

Parameters:

  • self – The reader instance.

  • signal_id – The FSR signal.

  • start_sample_id – The starting sample id to read. The first recorded sample is always 0. To get the first recorded sample_id, see jls_signal_def_s.sample_id_offset.

  • increment – The number of samples that form a single output summary.

  • data – [out] The statistics information, in the shape of data[data_length][JLS_SUMMARY_FSR_COUNT]. The elements are mean, standard_deviation, min, max. Use JLS_SUMMARY_FSR_MEAN, JLS_SUMMARY_FSR_STD, JLS_SUMMARY_FSR_MIN, and JLS_SUMMARY_FSR_MAX to index the values.

  • data_length – The number of statistics points to populate. data is at least JLS_SUMMARY_FSR_COUNT * data_length elements, each of float64 type (8 bytes). This argument allows efficient computation over many consecutive windows, as is common for displaying waveforms.

Returns:

0 or error code. JLS_ERROR_PARAMETER_INVALID when the arguments are invalid or start_sample_id + increment * data_length exceeds the signal length. JLS_ERROR_MESSAGE_INTEGRITY when the file data, index or summaries are corrupt.

int32_t jls_rd_annotations(struct jls_rd_s *self, uint16_t signal_id, int64_t timestamp, jls_rd_annotation_cbk_fn cbk_fn, void *cbk_user_data)#

Iterate over the annotations for a signal.

Parameters:

  • self – The reader instance.

  • signal_id – The signal id.

  • timestamp – The starting timestamp. Skip all prior annotations.

  • cbk_fn – The callback function that jls_rd_annotations() will call once for each matching annotation. Return 0 to continue to the next annotation or a non-zero value to stop iteration.

  • cbk_user_data – The arbitrary data provided to cbk_fn.

Returns:

0 or error code.

int32_t jls_rd_user_data(struct jls_rd_s *self, jls_rd_user_data_cbk_fn cbk_fn, void *cbk_user_data)#

Iterate over user data entries.

Parameters:

  • self – The reader instance.

  • cbk_fn – The callback function that jls_rd_user_data() will call once for each user data entry. Return 0 to continue to the next user data entry or a non-zero value to stop iteration.

  • cbk_user_data – The arbitrary data provided to cbk_fn.

Returns:

0 or error code.

int32_t jls_rd_utc(struct jls_rd_s *self, uint16_t signal_id, int64_t sample_id, jls_rd_utc_cbk_fn cbk_fn, void *cbk_user_data)#

Iterate over the UTC timestamps for a FSR signal.

Parameters:

  • self – The reader instance.

  • signal_id – The signal id.

  • sample_id – The starting sample_id. Skip all prior sample ids.

  • cbk_fn – The callback function that jls_rd_utc() will call once for UTC entries. Return 0 to continue to the next UTC entries or a non-zero value to stop iteration.

  • cbk_user_data – The arbitrary data provided to cbk_fn.

Returns:

0 or error code.

size_t jls_rd_tmap_length(struct jls_rd_s *self, uint16_t signal_id)#

Get the current number of entries in the FSR time map.

The time map loads on first use. UTC entries whose sample_id or timestamp does not increase are omitted. A failed load is not cached: the next time map call retries it and returns the error again.

Parameters:

  • self – The instance

  • signal_id – The signal id.

Returns:

The number of entries in this instance, or 0 on error.

int32_t jls_rd_sample_id_to_timestamp(struct jls_rd_s *self, uint16_t signal_id, int64_t sample_id, int64_t *timestamp)#

Convert from sample_id to timestamp for FSR signals.

Parameters:

  • self – The reader instance.

  • signal_id – The signal id.

  • sample_id – The sample id to convert.

  • timestamp – [out] The JLS timestamp for the sample_id.

Returns:

0 or error code.

int32_t jls_rd_timestamp_to_sample_id(struct jls_rd_s *self, uint16_t signal_id, int64_t timestamp, int64_t *sample_id)#

Convert from timestamp to sample_id for FSR signals.

Parameters:

  • self – The reader instance.

  • signal_id – The signal id.

  • timestamp – The JLS timestamp to convert.

  • sample_id – [out] The sample_id for timestamp.

Returns:

0 or error code.

int32_t jls_rd_tmap_get(struct jls_rd_s *self, uint16_t signal_id, size_t index, struct jls_utc_summary_entry_s *entry)#

Get a time map entry from the JLS reader instance.

Parameters:

  • self – The reader instance.

  • signal_id – The signal id.

  • index – The index

  • entry[out] – The time map entry.

Returns:

0 or error code.