C Reference¶
Initialisation¶
-
const int
ODC_INTEGERS_AS_DOUBLES
= 1¶ Represent integers as doubles in the API (default)
-
const int
ODC_INTEGERS_AS_LONGS
= 2¶ Represent integers as 64-bit integers in the API
-
int
odc_initialise_api
()¶ Initialises API, must be called before any other function
Note
This is only required if being used from a context where eckit::Main() is not otherwise initialised.
- Returns
Return code (OdcErrorValues)
-
int
odc_integer_behaviour
(int integerBehaviour)¶ Sets treatment of integers in the odc API
- Parameters
integerBehaviour – Desired integer behaviour (ODC_INTEGERS_AS_DOUBLES ODC_INTEGERS_AS_LONGS)
- Returns
Return code (OdcErrorValues)
Version Accessors¶
-
int
odc_version
(const char **version)¶ Retrieves the release version of the library in human-readable format, e.g.
1.3.0
- Parameters
version – Return variable for release version
- Returns
Return code (OdcErrorValues)
-
int
odc_vcs_version
(const char **version)¶ Retrieves version control checksum of the latest change, e.g.
a88011c007a0db48a5d16e296934a197eac2050a
- Parameters
version – Return variable for version control checksum
- Returns
Return code (OdcErrorValues)
Error Handling¶
-
enum
OdcErrorValues
¶ Return codes
Values:
-
enumerator
ODC_SUCCESS
¶ The function completed successfully
-
enumerator
ODC_ITERATION_COMPLETE
¶ All frames have been returned, and the loop can be terminated successfully.
-
enumerator
ODC_ERROR_GENERAL_EXCEPTION
¶ A known error was encountered. Call
odc_error_string()
with the returned code for details.
-
enumerator
ODC_ERROR_UNKNOWN_EXCEPTION
¶ An unexpected and unknown error was encountered. Call
odc_error_string()
with the returned code for details.
-
enumerator
-
typedef void (*
odc_failure_handler_t
)(void *context, int error_code)¶ Error handler callback function signature
- Parameters
context – Error handler context
error_code – Error code (OdcErrorValues)
-
const char *
odc_error_string
(int err)¶ Returns a human-readable error message for the last error given an error code
- Parameters
err – Error code (OdcErrorValues)
- Returns
Error message
-
int
odc_set_failure_handler
(odc_failure_handler_t handler, void *context)¶ Sets an error handler which will be called on error with the supplied context and an error code
- Parameters
handler – Error handler function
context – Error handler context
Values and Types¶
-
enum
OdcColumnType
¶ Column data types
Values:
-
enumerator
ODC_IGNORE
¶ Specifies that the column is ignored (invalid for real data)
-
enumerator
ODC_INTEGER
¶ Specifies the column contains integer data
-
enumerator
ODC_REAL
¶ Specifies the column contains 32-bit floating point values
-
enumerator
ODC_STRING
¶ Specifies the column contains character (string) data
-
enumerator
ODC_BITFIELD
¶ Specifies the column contains bitfield data
-
enumerator
ODC_DOUBLE
¶ Specifies the column contains 64-bit floating point values
-
enumerator
-
int
odc_column_type_count
(int *count)¶ Retrieves number of supported column data types
- Parameters
count – Return variable for number of data types
- Returns
Return code (OdcErrorValues)
-
int
odc_column_type_name
(int type, const char **type_name)¶ Retrieves a human-readable name of a column data type
- Parameters
type – Column data type (OdcColumnType)
type_name – Return variable for column data type name
- Returns
Return code (OdcErrorValues)
-
int
odc_set_missing_integer
(long missing_integer)¶ Sets the value that identifies a missing integer in the API
- Parameters
missing_integer – Missing integer value
- Returns
Return code (OdcErrorValues)
-
int
odc_set_missing_double
(double missing_double)¶ Sets the value that identifies a missing double in the API
- Parameters
missing_double – Missing double value
- Returns
Return code (OdcErrorValues)
-
int
odc_missing_integer
(long *missing_value)¶ Retrieves the value that identifies a missing integer in the API
- Parameters
missing_value – Return variable for missing integer value
- Returns
Return code (OdcErrorValues)
-
int
odc_missing_double
(double *missing_value)¶ Retrieves the value that identifies a missing double in the API
- Parameters
missing_value – Return variable for missing double value
- Returns
Return code (OdcErrorValues)
Reader¶
-
typedef struct odc_reader_t
odc_reader_t
¶ Opaque type for the Reader object. Controls the ODB-2 data stream and associated resources, and gives access to the underlying frames.
-
typedef long (*
odc_stream_read_t
)(void *context, void *buffer, long length)¶ Reader stream handler callback function signature. Functions analogously to the POSIX read() function.
- Parameters
context – Stream handler context
buffer – Memory buffer to handle
buffer – Size of the memory buffer
-
int
odc_open_path
(odc_reader_t **reader, const char *filename)¶ Creates a reader and opens the specified file path
- Parameters
reader – Reader instance
filename – File path to open
- Returns
Return code (OdcErrorValues)
-
int
odc_open_file_descriptor
(odc_reader_t **reader, int fd)¶ Creates a reader from an already open file descriptor.
The file descriptor will be duplicated so the calling code is safe to close the file descriptor.
- Parameters
reader – Reader instance
fd – File descriptor
- Returns
Return code (OdcErrorValues)
-
int
odc_open_buffer
(odc_reader_t **reader, const void *data, long length)¶ Creates a reader from a memory buffer
- Parameters
reader – Reader instance
data – Memory buffer
length – Length of memory buffer
- Returns
Return code (OdcErrorValues)
-
int
odc_open_stream
(odc_reader_t **reader, void *context, odc_stream_read_t stream_proc)¶ Creates a reader associated to a custom stream handler. The callback specified will be called in the same way as the POSIX read() function to obtain data from the custom stream.
- Parameters
reader – Reader instance
context – Stream handler context
stream_proc – Stream handler function
- Returns
Return code (OdcErrorValues)
-
int
odc_close
(const odc_reader_t *reader)¶ Closes opened resource and destroys the reader
- Parameters
reader – Reader instance
- Returns
Return code (OdcErrorValues)
Frame¶
-
typedef struct odc_frame_t
odc_frame_t
¶ Opaque type for the Frame object. Provides a viewport onto a chunk of contiguous data within the ODB-2 stream.
-
int
odc_new_frame
(odc_frame_t **frame, odc_reader_t *reader)¶ Creates a frame instance associated with a specific reader instance, for interrogating ODB-2 data
- Parameters
frame – Frame instance
reader – Reader instance
- Returns
Return code (OdcErrorValues)
-
int
odc_free_frame
(const odc_frame_t *frame)¶ Deallocates frame object and associated resources.
- Parameters
frame – Frame instance
- Returns
Return code (OdcErrorValues)
-
int
odc_next_frame
(odc_frame_t *frame)¶ Advances the viewport to the next frame in the stream
- Parameters
frame – Frame instance
- Returns
Return code (OdcErrorValues)
-
int
odc_next_frame_aggregated
(odc_frame_t *frame, long maximum_rows)¶ Advances the viewport to the next logical frame in the stream
- Parameters
frame – Frame instance
maximum_rows – Maximum number of rows to aggregate into one logical frame
- Returns
Return code (OdcErrorValues)
-
int
odc_copy_frame
(odc_frame_t *source_frame, odc_frame_t **copy)¶ Creates an independent copy of the frame object, resulting in an independent viewport on the ODB data stream with its own associated resources. To use the new copied frame independently from the first requires the ODB-2 data stream to be seekable.
- Parameters
source_frame – Source frame instance to copy from
copy – Target frame instance to copy to
- Returns
Return code (OdcErrorValues)
-
int
odc_frame_row_count
(const odc_frame_t *frame, long *count)¶ Retrieves number of rows in the frame
- Parameters
frame – Frame instance
count – Return variable for number of rows
- Returns
Return code (OdcErrorValues)
-
int
odc_frame_column_count
(const odc_frame_t *frame, int *count)¶ Retrieves number of columns in the frame
- Parameters
frame – Frame instance
count – Return variable for number of columns
- Returns
Return code (OdcErrorValues)
-
int
odc_frame_column_attributes
(const odc_frame_t *frame, int col, const char **name, int *type, int *element_size, int *bitfield_count)¶ Retrieves column attributes from current frame
- Parameters
frame – Frame instance
col – Target column index
name – (optional) Return variable for column name
type – (optional) Return variable for column type
element_size – (optional) Return variable for column size in bytes
bitfield_count – (optional) Return variable for number of column bitfields
- Returns
Return code (OdcErrorValues)
-
int
odc_frame_bitfield_attributes
(const odc_frame_t *frame, int col, int entry, const char **name, int *offset, int *size)¶ Retrieves bitfield attributes of a column
- Parameters
frame – Frame instance
col – Target column index
entry – Target bitfield index
name – (optional) Return variable for bitfield name
offset – (optional) Return variable for bitfield offset
size – (optional) Return variable for bitfield size in bits
- Returns
Return code (OdcErrorValues)
-
int
odc_frame_properties_count
(const odc_frame_t *frame, int *nproperties)¶ Retrieves the number of properties encoded in the frame
- Parameters
frame – Frame instance
nproperties – Return variable for number of properties
- Returns
Return code (OdcErrorValues)
-
int
odc_frame_property_idx
(const odc_frame_t *frame, int idx, const char **key, const char **value)¶ Retrieves the property key and value by its index
- Parameters
frame – Frame instance
idx – Property index
key – Return variable for property key
value – Return variable for property value
- Returns
Return code (OdcErrorValues)
-
int
odc_frame_property
(const odc_frame_t *frame, const char *key, const char **value)¶ Retrieves the property value by its key
- Parameters
frame – Frame instance
key – Property key
value – Return variable for property value
- Returns
Return code (OdcErrorValues)
Decoder¶
-
typedef struct odc_decoder_t
odc_decoder_t
¶ Opaque type for the Decoder object. Specifies which ODB-2 columns should be decoded and the memory that should be used for the decoded data.
-
int
odc_new_decoder
(odc_decoder_t **decoder)¶ Creates a decoder instance for decoding ODB-2 format
- Parameters
decoder – Decoder instance
- Returns
Return code (OdcErrorValues)
-
int
odc_free_decoder
(const odc_decoder_t *decoder)¶ Deallocates memory used up by a decoder
- Parameters
decoder – Decoder instance
- Returns
Return code (OdcErrorValues)
-
int
odc_decoder_defaults_from_frame
(odc_decoder_t *decoder, const odc_frame_t *frame)¶ Configures a decoder to decode all data contained in the supplied frame
- Parameters
decoder – Decoder instance
frame – Frame instance
- Returns
Return code (OdcErrorValues)
-
int
odc_decoder_set_column_major
(odc_decoder_t *decoder, bool columnMajor)¶ Instructs the decoder whether to output in column-major form
- Parameters
decoder – Decoder instance
columnMajor – Whether to output in column-major form
- Returns
Return code (OdcErrorValues)
-
int
odc_decoder_set_row_count
(odc_decoder_t *decoder, long nrows)¶ Sets number of rows to allocate in a decoder
- Parameters
decoder – Decoder instance
nrows – Number of rows to allocate
- Returns
Return code (OdcErrorValues)
-
int
odc_decoder_row_count
(const odc_decoder_t *decoder, long *nrows)¶ Retrieves number of rows that are allocated in a decoder
- Parameters
decoder – Decoder instance
nrows – Return variable for number of rows
- Returns
Return code (OdcErrorValues)
-
int
odc_decoder_set_data_array
(odc_decoder_t *decoder, void *data, long width, long height, bool columnMajor)¶ Sets an output data array into which the data may be decoded
- Parameters
decoder – Decoder instance
data – Data array to decode into
width – Width of data array in bytes
height – Height of data array in rows
columnMajor – Whether the column-major memory layout is used
- Returns
Return code (OdcErrorValues)
-
int
odc_decoder_data_array
(const odc_decoder_t *decoder, const void **data, long *width, long *height, bool *columnMajor)¶ Retrieves the output data array into which the data may be decoded
- Parameters
decoder – Decoder instance
data – (optional) Data array to decode into
width – (optional) Width of data array in bytes
height – (optional) Height of data array in rows
columnMajor – (optional) Whether the column-major memory layout is used
- Returns
Return code (OdcErrorValues)
-
int
odc_decoder_add_column
(odc_decoder_t *decoder, const char *name)¶ Adds a data column to a decoder
- Parameters
decoder – Decoder instance
name – Data column name
- Returns
Return code (OdcErrorValues)
-
int
odc_decoder_column_count
(const odc_decoder_t *decoder, int *count)¶ Retrieves number of columns that are allocated in a decoder
- Parameters
decoder – Decoder instance
count – Return variable for number of columns
- Returns
Return code (OdcErrorValues)
-
int
odc_decoder_column_set_data_size
(odc_decoder_t *decoder, int col, int element_size)¶ Sets the decoded data size for a column in bytes
- Parameters
decoder – Decoder instance
col – Column index
element_size – Column data size in bytes
- Returns
Return code (OdcErrorValues)
-
int
odc_decoder_column_set_data_array
(odc_decoder_t *decoder, int col, int element_size, int stride, void *data)¶ Sets an output data array into which the data associated with the column can be decoded
- Parameters
decoder – Decoder instance
col – Column index
element_size – Column data size in bytes
stride – Column data width in bytes
data – Column data array
- Returns
Return code (OdcErrorValues)
-
int
odc_decoder_column_data_array
(const odc_decoder_t *decoder, int col, int *element_size, int *stride, const void **data)¶ Retrieves the buffer and data layout into which the data has been decoded
- Parameters
decoder – Decoder instance
col – Column index
element_size – (optional) Return variable for column data size in bytes
stride – (optional) Return variable for column data width in bytes
data – (optional) Return variable for column data array
- Returns
Return code (OdcErrorValues)
-
int
odc_decode
(odc_decoder_t *decoder, const odc_frame_t *frame, long *rows_decoded)¶ Decodes the data described by the frame into the configured data array(s)
- Parameters
decoder – Decoder instance
frame – Frame instance
rows_decoded – (optional) Return variable for number of decoded rows
- Returns
Return code (OdcErrorValues)
-
int
odc_decode_threaded
(odc_decoder_t *decoder, const odc_frame_t *frame, long *rows_decoded, int nthreads)¶ Decodes the data described by the frame into the configured data array(s).
If the frame is a logical one, parallelise the decoding over multiple threads.
- Parameters
decoder – Decoder instance
frame – Frame instance
rows_decoded – (optional) Return variable for number of decoded rows
nthreads – Number of threads
- Returns
Return code (OdcErrorValues)
Encoder¶
-
typedef struct odc_encoder_t
odc_encoder_t
¶ Opaque type for the Encoder object. Describes the column properties and the data layout of the source data for encoding into ODB-2 frames.
-
typedef long (*
odc_stream_write_t
)(void *context, const void *buffer, long length)¶ Encoder stream handler function signature
- Parameters
context – Stream handler context
buffer – Memory buffer to handle
length – Size of memory buffer in bytes
-
int
odc_new_encoder
(odc_encoder_t **encoder)¶ Creates an encoder instance for encoding into ODB-2 format
- Parameters
encoder – Encoder instance
- Returns
Return code (OdcErrorValues)
-
int
odc_free_encoder
(const odc_encoder_t *encoder)¶ Deallocates memory used up by an encoder
- Parameters
encoder – Encoder instance
- Returns
Return code (OdcErrorValues)
-
int
odc_encoder_add_property
(odc_encoder_t *encoder, const char *key, const char *value)¶ Adds a key/value property to encode as part of the frame
- Parameters
encoder – Encoder instance
key – Property key
value – Property value
- Returns
Return code (OdcErrorValues)
-
int
odc_encoder_set_row_count
(odc_encoder_t *encoder, long nrows)¶ Sets number of rows to allocate in an encoder
- Parameters
encoder – Encoder instance
nrows – Number of rows
- Returns
Return code (OdcErrorValues)
-
int
odc_encoder_set_rows_per_frame
(odc_encoder_t *encoder, long rows_per_frame)¶ Sets number of rows to encode per frame
- Parameters
encoder – Encoder instance
rows_per_frame – Number of rows per frame
- Returns
Return code (OdcErrorValues)
-
int
odc_encoder_set_data_array
(odc_encoder_t *encoder, const void *data, long width, long height, int columnMajorWidth)¶ Sets input data array from which data may be encoded
- Parameters
encoder – Encoder instance
data – Data array to encode
width – Width of the data array in bytes
height – Height of the data array in rows
columnMajorWidth – Column size in bytes for column-major layout, if zero interpret as row-major layout
- Returns
Return code (OdcErrorValues)
-
int
odc_encoder_add_column
(odc_encoder_t *encoder, const char *name, int type)¶ Adds a data column to current encoder
- Parameters
encoder – Encoder instance
name – Column name
type – Column data type (OdcColumnType)
- Returns
Return code (OdcErrorValues)
-
int
odc_encoder_column_set_data_size
(odc_encoder_t *encoder, int col, int element_size)¶ Sets the source data size for a column
- Parameters
encoder – Encoder instance
col – Column index
element_size – Column data size in bytes
- Returns
Return code (OdcErrorValues)
-
int
odc_encoder_column_set_data_array
(odc_encoder_t *encoder, int col, int element_size, int stride, const void *data)¶ Sets a custom data layout and data array for a column
- Parameters
encoder – Encoder instance
col – Column index
element_size – Column size in bytes
stride – Column width in bytes
data – Column data array
- Returns
Return code (OdcErrorValues)
-
int
odc_encoder_column_add_bitfield
(odc_encoder_t *encoder, int col, const char *name, int nbits)¶ Adds a bitfield to a column
- Parameters
encoder – Encoder instance
col – Column index
name – Bitfield name
nbits – Bitfield size in bits
- Returns
Return code (OdcErrorValues)
-
int
odc_encode_to_stream
(odc_encoder_t *encoder, void *context, odc_stream_write_t write_fn, long *bytes_encoded)¶ Encodes ODB-2 into a stream handler
- Parameters
encoder – Encoder instance
context – Stream handler context
write_fn – Stream handler function
bytes_encoded – Return variable for number of encoded bytes
- Returns
Return code (OdcErrorValues)
-
int
odc_encode_to_file_descriptor
(odc_encoder_t *encoder, int fd, long *bytes_encoded)¶ Encodes ODB-2 into an already open file descriptor
- Parameters
encoder – Encoder instance
fd – File descriptor
bytes_encoded – (optional) Return variable for number of encoded bytes
- Returns
Return code (OdcErrorValues)
-
int
odc_encode_to_buffer
(odc_encoder_t *encoder, void *buffer, long length, long *bytes_encoded)¶ Encodes ODB-2 into a pre-allocated memory buffer
- Parameters
encoder – Encoder instance
buffer – Memory buffer
length – Buffer size
bytes_encoded – (optional) Return variable for number of encoded bytes
- Returns
Return code (OdcErrorValues)