Unstructured Data Interface

Unstructured data interface for any type of data, for example reading an integer from a file. There are currently two different implementations of the SDatasource object.

Also see SDatasource Example.

Definitions

speect object SDatasource

The data source structure.

Provides a generic interface to different data sources, where a data source can be anything that can be read from and/or written to. Integer I/O Functions and Floating Point I/O Functions are also provided for data source I/O.

SDatasource Structure

speect class SDatasourceClass

The data source class structure.

SDatasourceClass Structure

typedef enum s_byte_order

An enum to define the byte order of a data source.

Values:

• S_BYTEORDER_BE -

  big endian byte order.

• S_BYTEORDER_LE -

  little endian byte order.

typedef enum s_seek_mode

An enum to define the relative position of seek.

Values:

• S_SEEK_SET = SEEK_SET -

  Relative to beginning.

• S_SEEK_CUR = SEEK_CUR -

  Relative to current position.

• S_SEEK_END = SEEK_END -

  Relative to end.

Macros

macro S_DATASOURCE(SELF)

Return the given SDatasource child class object as a SDatasource object.

Parameters:

• SELF –

  The given object.

Return:

Given object as SDatasource* type.

Note:

This casting is not safety checked.

Functions

Read

size_t SDatasourceRead(SDatasource *self, void *ptr, size_t size, size_t nmemb, s_erc *error)

Read from a data source.

Reads nmemb items of size bytes from the data source into a buffer.

Parameters:

• self –

  The data source to read from.

• ptr –

  The buffer to read the data into.

• size –

  The size of the items.

• nmemb –

  Number of items to read.

• error –

  Error code.

Return:

The number of bytes read.

Note:

Can set S_IOEOF (end-of-file) error, which must be interpreted by the caller if it is an error or not.

size_t SDatasourceReadAt(SDatasource *self, void *ptr, size_t size, size_t nmemb, long pos, s_erc *error)

Read from a data source starting at a given offset position.

Reads nmemb items of size bytes from the data source into a buffer starting at pos.

Parameters:

• self –

  The data source to read from.

• ptr –

  The buffer to read the data into.

• size –

  The size of the items.

• nmemb –

  Number of items to read.

• pos –

  The offset to start reading from.

• error –

  Error code.

Return:

The number of bytes read.

Note:

Can set S_IOEOF (end-of-file) error, which must be interpreted by the caller if it is an error or not.

Write

size_t SDatasourceWrite(SDatasource *self, const void *ptr, size_t size, size_t nmemb, s_erc *error)

Write to a data source.

Writes nmemb items of size bytes from a buffer into the data source.

Parameters:

• self –

  The data source to write from.

• ptr –

  The buffer containing the data.

• size –

  The size of the items.

• nmemb –

  Number of items to write.

• error –

  Error code.

Return:

The number of bytes written.

size_t SDatasourceWriteAt(SDatasource *self, const void *ptr, size_t size, size_t nmemb, long pos, s_erc *error)

Write to a data source starting at a given offset position.

Writes nmemb items of size bytes from a buffer into the data source starting at pos.

Parameters:

• self –

  The data source to write from.

• ptr –

  The buffer containing the data.

• size –

  The size of the items.

• nmemb –

  Number of items to write.

• pos –

  The offset to start writing from.

• error –

  Error code.

Return:

The number of bytes written.

Position/Byte Order

long SDatasourceTell(SDatasource *self, s_erc *error)

Returns the current position in the data source.

If the underlying data source does not support this operation, a value of -1 is returned.

Parameters:

• self –

  The data source.

• error –

  Error code.

Return:

The offset position.

void SDatasourceSeek(SDatasource *self, long pos, s_seek_mode mode, s_erc *error)

Seeks to the given position in the data source, where mode is one of: s_seek_mode.

Parameters:

• self –

  The data source.

• pos –

  The position.

• mode –

  The position relative to s_seek_mode.

• error –

  Error code.

void SDatasourceSetByteOrder(SDatasource *self, s_byte_order order, s_erc *error)

Configures the byte order to be used by integer read/write operations.

Order may be one of s_byte_order.

Parameters:

• self –

  The data source.

• order –

  The order of the source,

Parameters:

• error –

  Error code.

See also:

s_byte_order.

Note:

At initialization of any object derived from SDatasource the byte order is set to bigendian.

Integer I/O

uint8 s_uint8_read(SDatasource *ds, s_erc *error)

Read a uint8 value from a data source.

Parameters:

• ds –

  The data source from which to read the uint8 value.

• error –

  Error code.

Return:

The read uint8 value.

uint8 s_uint8_read_at(SDatasource *ds, long pos, s_erc *error)

Read a uint8 value from a data source starting at a given offset position.

Parameters:

• ds –

  The data source from which to read the uint8 value.

• pos –

  The offset to start reading from.

• error –

  Error code.

Return:

The read uint8 value.

void s_uint8_write(SDatasource *ds, uint8 i, s_erc *error)

Write a uint8 value to a data source.

Parameters:

• ds –

  The data source which to write the uint8 value to.

• i –

  The uint8 value to write.

• error –

  Error code.

void s_uint8_write_at(SDatasource *ds, uint8 i, long pos, s_erc *error)

Write a uint8 value to a data source with an offset.

Parameters:

• ds –

  The data source which to write the uint8 value to.

• i –

  The uint8 value to write.

• pos –

  The offset.

• error –

  Error code.

uint16 s_uint16_read(SDatasource *ds, s_erc *error)

Read a uint16 value from a data source.

Parameters:

• ds –

  The data source from which to read the uint16 value.

• error –

  Error code.

Return:

The read uint16 value.

uint16 s_uint16_read_at(SDatasource *ds, long pos, s_erc *error)

Read a uint16 value from a data source starting at a given offset position.

Parameters:

• ds –

  The data source from which to read the uint16 value.

• pos –

  The offset to start reading from.

• error –

  Error code.

Return:

The read uint16 value.

void s_uint16_write(SDatasource *ds, uint16 i, s_erc *error)

Write a uint16 value to a data source.

Parameters:

• ds –

  The data source which to write the uint16 value to.

• i –

  The uint16 value to write.

• error –

  Error code.

void s_uint16_write_at(SDatasource *ds, uint16 i, long pos, s_erc *error)

Write a uint16 value to a data source with an offset.

Parameters:

• ds –

  The data source which to write the uint16 value to.

• i –

  The uint16 value to write.

• pos –

  The offset.

• error –

  Error code.

uint32 s_uint32_read(SDatasource *ds, s_erc *error)

Read a uint32 value from a data source.

Parameters:

• ds –

  The data source from which to read the uint32 value.

• error –

  Error code.

Return:

The read uint32 value.

uint32 s_uint32_read_at(SDatasource *ds, long pos, s_erc *error)

Read a uint32 value from a data source starting at a given offset position.

Parameters:

• ds –

  The data source from which to read the uint32 value.

• pos –

  The offset to start reading from.

• error –

  Error code.

Return:

The read uint32 value.

void s_uint32_write(SDatasource *ds, uint32 i, s_erc *error)

Write a uint32 value to a data source.

Parameters:

• ds –

  The data source which to write the uint32 value to.

• i –

  The uint32 value to write.

• error –

  Error code.

void s_uint32_write_at(SDatasource *ds, uint32 i, long pos, s_erc *error)

Write a uint32 value to a data source with an offset.

Parameters:

• ds –

  The data source which to write the uint32 value to.

• i –

  The uint32 value to write.

• pos –

  The offset.

• error –

  Error code.

sint8 s_sint8_read(SDatasource *ds, s_erc *error)

Read a sint8 value from a data source.

Parameters:

• ds –

  The data source from which to read the sint8 value.

• error –

  Error code.

Return:

The read sint8 value.

sint8 s_sint8_read_at(SDatasource *ds, long pos, s_erc *error)

Read a sint8 value from a data source starting at a given offset position.

Parameters:

• ds –

  The data source from which to read the sint8 value.

• pos –

  The offset to start reading from.

• error –

  Error code.

Return:

The read sint8 value.

void s_sint8_write(SDatasource *ds, sint8 i, s_erc *error)

Write a sint8 value to a data source.

Parameters:

• ds –

  The data source which to write the sint8 value to.

• i –

  The sint8 value to write.

• error –

  Error code.

void s_sint8_write_at(SDatasource *ds, sint8 i, long pos, s_erc *error)

Write a sint8 value to a data source with an offset.

Parameters:

• ds –

  The data source which to write the sint8 value to.

• i –

  The sint8 value to write.

• pos –

  The offset.

• error –

  Error code.

sint16 s_sint16_read(SDatasource *ds, s_erc *error)

Read a sint16 value from a data source.

Parameters:

• ds –

  The data source from which to read the sint16 value.

• error –

  Error code.

Return:

The read sint16 value.

sint16 s_sint16_read_at(SDatasource *ds, long pos, s_erc *error)

Read a sint16 value from a data source starting at a given offset position.

Parameters:

• ds –

  The data source from which to read the sint16 value.

• pos –

  The offset to start reading from.

• error –

  Error code.

Return:

The read sint16 value.

void s_sint16_write(SDatasource *ds, sint16 i, s_erc *error)

Write a sint16 value to a data source.

Parameters:

• ds –

  The data source which to write the sint16 value to.

• i –

  The sint16 value to write.

• error –

  Error code.

void s_sint16_write_at(SDatasource *ds, sint16 i, long pos, s_erc *error)

Write a sint16 value to a data source with an offset.

Parameters:

• ds –

  The data source which to write the sint16 value to.

• i –

  The sint16 value to write.

• pos –

  The offset.

• error –

  Error code.

sint32 s_sint32_read(SDatasource *ds, s_erc *error)

Read a sint32 value from a data source.

Parameters:

• ds –

  The data source from which to read the sint32 value.

• error –

  Error code.

Return:

The read sint32 value.

sint32 s_sint32_read_at(SDatasource *ds, long pos, s_erc *error)

Read a sint32 value from a data source starting at a given offset position.

Parameters:

• ds –

  The data source from which to read the sint32 value.

• pos –

  The offset to start reading from.

• error –

  Error code.

Return:

The read sint32 value.

void s_sint32_write(SDatasource *ds, sint32 i, s_erc *error)

Write a sint32 value to a data source.

Parameters:

• ds –

  The data source which to write the sint32 value to.

• i –

  The sint32 value to write.

• error –

  Error code.

void s_sint32_write_at(SDatasource *ds, sint32 i, long pos, s_erc *error)

Write a sint32 value to a data source with an offset.

Parameters:

• ds –

  The data source which to write the sint32 value to.

• i –

  The sint32 value to write.

• pos –

  The offset.

• error –

  Error code.

Floating Point I/O

float s_float_read(SDatasource *ds, s_erc *error)

Read a float value from a data source.

Parameters:

• ds –

  The data source from which to read the float value.

• error –

  Error code.

Return:

The read float value.

float s_float_read_at(SDatasource *ds, long pos, s_erc *error)

Read a float value from a data source starting at a given offset position.

Parameters:

• ds –

  The data source from which to read the float value.

• pos –

  The offset to start reading from.

• error –

  Error code.

Return:

The read float value.

void s_float_write(SDatasource *ds, float f, s_erc *error)

Write a float value to a data source.

Parameters:

• ds –

  The data source which to write the float value to.

• f –

  The float value to write.

• error –

  Error code.

void s_float_write_at(SDatasource *ds, float f, long pos, s_erc *error)

Write a float value to a data source with an offset.

Parameters:

• ds –

  The data source which to write the float value to.

• f –

  The float value to write.

• pos –

  The offset.

• error –

  Error code.

double s_double_read(SDatasource *ds, s_erc *error)

Read a double value from a data source.

Parameters:

• ds –

  The data source from which to read the double value.

• error –

  Error code.

Return:

The read double value.

double s_double_read_at(SDatasource *ds, long pos, s_erc *error)

Read a double value from a data source starting at a given offset position.

Parameters:

• ds –

  The data source from which to read the double value.

• pos –

  The offset to start reading from.

• error –

  Error code.

Return:

The read double value.

void s_double_write(SDatasource *ds, double d, s_erc *error)

Write a double value to a data source.

Parameters:

• ds –

  The data source which to write the double value to.

• d –

  The double value to write.

• error –

  Error code.

void s_double_write_at(SDatasource *ds, double d, long pos, s_erc *error)

Write a double value to a data source with an offset.

Parameters:

• ds –

  The data source which to write the double value to.

• d –

  The double value to write.

• pos –

  The offset.

• error –

  Error code.

Implementations

Two different implementations of the abstract SDatasource object:

SFilesource

speect object SFilesource

The file source structure.

Provides an interface to a file based data source.

SFilesource Specific Functions

SDatasource *SFilesourceOpenHandle(FILE *f, s_erc *error)

Create a data source from a previously opened file.

Parameters:

• f –

  A file handle pointer to a previously opened file.

• error –

  Error code.

Return:

Pointer to the newly created data source.

SDatasource *SFilesourceOpenFile(const char *path, const char *mode, s_erc *error)

Open a file to be used as a data source.

Open the file at path, where mode is character string as used by the standard function fopen().

Parameters:

• path –

  The path and name of the file to open.

• mode –

  The mode string as used by the standard function fopen().

• error –

  Error code.

Return:

Pointer to the newly created data source.

SMMapFilesource

speect object SMMapFilesource

The mmap file source structure.

Provides an interface to a memory mapped file based data source.

SMMapFilesource Specific Functions

SDatasource *SMMapFilesourceOpenFile(const char *path, s_erc *error)

Opens a file to be memory mapped and used as a data source.

Open the file at path, where mode is character string as used by the standard function fopen().

Parameters:

• path –

  The path and name of the file to open.

• error –

  Error code.

Return:

Pointer to the newly created data source.

Note:

The SMMapFilesource data source is read only and does not implement SDatasourceClass methods write (SDatasourceWrite) and write_at (SDatasourceWriteAt).