JLS Reader

group jls_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.

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.

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.

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.

For data_length 1, the statistics are sample-accurate. For larger data_lengths, the external boundaries for start and end are computed exactly. The internal boundaries are approximated, perfect for waveform display, but perhaps not suitable for other use cases. If you need sample accurate statistics over multiple increments, call this function repeatedly with data_length 1.

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.

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.

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.