epr_api.h File Reference

#include <stdio.h>
#include "epr_ptrarray.h"

Go to the source code of this file.

Data Structures

struct EPR_ProductId

The EPR_ProductId structure contains information about an ENVISAT product file which has been opened with the epr_open_product() function. More...

struct EPR_DatasetId

The EPR_DatasetId structure contains information about a dataset within an ENVISAT product file which has been opened with the epr_open_product() API function. More...

struct EPR_DSD

The EPR_DSD structure contains information about the propertier of a dataset properties and its location within an ENVISAT product file. More...

struct EPR_Record

The EPR_Record structure represents a record instance read from an ENVISAT dataset. More...

struct EPR_Field

Represents a field within a record. More...

struct EPR_Raster

Represents a raster in which data will be stored. More...

struct EPR_DatasetRef

The EPR_DatasetRef structure represents the information from dddb
with the reference to data name (in dddb), field-name and index of the element in field-array, in which (by name) searchable values are located. More...

struct EPR_FlagDef

Represents a flag-field within a flag-record. More...

struct EPR_BandId

The EPR_BandId structure contains information about a band within an ENVISAT product file which has been opened with the epr_open_product() API function. More...

struct EPR_Time

Represents a binary time value field in ENVISAT records. More...

Defines

#define EPR_PRODUCT_API_NAME_STR   "ENVISAT Product Reader API"

#define EPR_PRODUCT_API_VERSION_STR   "2.0.5"

#define EPR_MAGIC_PRODUCT_ID   0xCAFFEE64

#define EPR_MAGIC_DATASET_ID   0xEFEABDCA

#define EPR_MAGIC_BAND_ID   0xFEC21ABD

#define EPR_MAGIC_RECORD   0x7BABACAE

#define EPR_MAGIC_FIELD   0xBA0BABBA

#define EPR_MAGIC_RASTER   0x0BABA0EB

#define EPR_MAGIC_FLAG_DEF   0xCABA11AD

#define TRUE   1

#define FALSE   0

#define EPR_PRODUCT_ID_STRLEN   48

Typedefs

typedef enum EPR_DataTypeId EPR_EDataTypeId

typedef enum EPR_ErrCode EPR_EErrCode

typedef enum EPR_LogLevel EPR_ELogLevel

typedef enum EPR_SampleModel EPR_ESampleModel

typedef enum EPR_ScalingMethod EPR_EScalingMethod

typedef struct EPR_ProductId EPR_SProductId

typedef struct EPR_DatasetId EPR_SDatasetId

typedef struct EPR_BandId EPR_SBandId

typedef struct EPR_Record EPR_SRecord

typedef struct EPR_RecordInfo EPR_SRecordInfo

typedef struct EPR_Field EPR_SField

typedef struct EPR_FieldInfo EPR_SFieldInfo

typedef struct EPR_DSD EPR_SDSD

typedef struct EPR_Raster EPR_SRaster

typedef struct EPR_FlagDef EPR_SFlagDef

typedef struct EPR_ParamElem EPR_SParamElem

typedef struct EPR_Time EPR_STime

typedef struct EPR_DatasetRef EPR_SDatasetRef

typedef struct EPR_BitmaskTerm EPR_SBitmaskTerm

typedef struct EPR_FlagSet EPR_SFlagSet

typedef void(* EPR_FErrHandler )(EPR_EErrCode err_code, const char *err_message)

typedef void(* EPR_FLogHandler )(EPR_ELogLevel log_level, const char *log_message)

typedef int boolean

typedef unsigned char uchar

typedef unsigned short ushort

typedef unsigned int uint

typedef unsigned long ulong

typedef long EPR_Magic

Enumerations

enum EPR_DataTypeId {
  e_tid_unknown = 0, e_tid_uchar = 1, e_tid_char = 2, e_tid_ushort = 3,
  e_tid_short = 4, e_tid_ulong = 5, e_tid_long = 6, e_tid_float = 7,
  e_tid_double = 8, e_tid_string = 11, e_tid_spare = 13, e_tid_time = 21
}

The EPR_DataTypeId enumeration lists all possible data types for field elements in ENVISAT dataset records. More...

enum EPR_ErrCode {
  e_err_none = 0, e_err_null_pointer = 1, e_err_illegal_arg = 2, e_err_illegal_state = 3,
  e_err_out_of_memory = 4, e_err_index_out_of_range = 5, e_err_illegal_conversion = 6, e_err_illegal_data_type = 7,
  e_err_file_not_found = 101, e_err_file_access_denied = 102, e_err_file_read_error = 103, e_err_file_write_error = 104,
  e_err_file_open_failed = 105, e_err_file_close_failed = 106, e_err_api_not_initialized = 201, e_err_invalid_product_id = 203,
  e_err_invalid_record = 204, e_err_invalid_band = 205, e_err_invalid_raster = 206, e_err_invalid_dataset_name = 207,
  e_err_invalid_field_name = 208, e_err_invalid_record_name = 209, e_err_invalid_product_name = 210, e_err_invalid_band_name = 211,
  e_err_invalid_data_format = 212, e_err_invalid_value = 213, e_err_invalid_keyword_name = 214, e_err_unknown_endian_order = 216,
  e_err_flag_not_found = 301, e_err_invalid_ddbb_format = 402
}

The EPR_ErrCode enumeration lists all possible error codes for the ENVISAT product reader API. More...

enum EPR_LogLevel { e_log_debug = -1, e_log_info = 0, e_log_warning = 1, e_log_error = 2 }

The EPR_LogLevel enumeration lists possible log levels for the ENVISAT product reader API. More...

enum EPR_SampleModel {
  e_smod_1OF1 = 0, e_smod_1OF2 = 1, e_smod_2OF2 = 2, e_smod_3TOI = 3,
  e_smod_2TOF = 4
}

enum EPR_ScalingMethod { e_smid_non = 0, e_smid_lin = 1, e_smid_log = 2 }

Functions

int epr_init_api (EPR_ELogLevel log_level, EPR_FLogHandler log_handler, EPR_FErrHandler err_handler)

============================ (1) Initialisation ==========================

void epr_close_api ()

Closes the ENVISAT product reader API by releasing all resources allocated by the API.

int epr_set_log_level (EPR_ELogLevel log_level)

Sets the log level for the ENVISAT API.

void epr_set_log_handler (EPR_FLogHandler log_handler)

Sets the log handler for the ENVISAT API.

void epr_log_message (EPR_ELogLevel log_level, const char *log_message)

A default implementation for a logging function to be passed into the epr_init() function.

void epr_set_err_handler (EPR_FErrHandler err_handler)

Sets the error handler for the ENVISAT API.

EPR_EErrCode epr_get_last_err_code ()

Gets the error code of the error that occured during the last API function call.

const char * epr_get_last_err_message ()

Gets the error message of the error that occured during the last API function call.

void epr_clear_err ()

Clears the last error.

EPR_SProductId * epr_open_product (const char *product_file_path)

Opens the ENVISAT product file with the given file path,
reads MPH, SPH and all DSDs,
organized the table with parameter of line length and tie points number;
returns a file identifier for the product.

int epr_close_product (EPR_SProductId *product_id)

Closes the ENVISAT product file determined by the given product identifier.

ulong epr_get_scene_width (const EPR_SProductId *product_id)

Gets the product's scene width in pixels.

ulong epr_get_scene_height (const EPR_SProductId *product_id)

Gets the product's scene height in pixels.

uint epr_get_num_datasets (EPR_SProductId *product_id)

Gets the number off all datasets contained in a product.

EPR_SDatasetId * epr_get_dataset_id_at (EPR_SProductId *product_id, uint index)

Gets the dataset_id at the specified position within the product.

EPR_SDatasetId * epr_get_dataset_id (EPR_SProductId *product_id, const char *dataset_name)

Gets the dataset_id coresponding to the specified dataset name.

const char * epr_get_dataset_name (EPR_SDatasetId *dataset_id)

Gets the name of the dataset for the given dataset ID.

const char * epr_get_dsd_name (const EPR_SDatasetId *dataset_id)

Gets the name of the dsd for the given dataset ID.

EPR_SRecord * epr_get_mph (const EPR_SProductId *product_id)

Gets the MPH record from the given product_id.

EPR_SRecord * epr_get_sph (const EPR_SProductId *product_id)

Gets the SPH record from the given product_id.

const EPR_SDSD * epr_get_dsd (const EPR_SDatasetId *dataset_id)

Gets the dataset descriptor (DSD) for the dataset specified by dataset_id.

uint epr_get_num_records (const EPR_SDatasetId *dataset_id)

Gets the number of records of the dataset specified by dataset_id.

uint epr_get_num_dsds (const EPR_SProductId *product_id)

EPR_SDSD * epr_get_dsd_at (const EPR_SProductId *product_id, uint dsd_index)

EPR_SRecord * epr_create_record (EPR_SDatasetId *dataset_id)

Creates a new, empty record with a structure compatible with the dataset specified by dataset_id.

EPR_SRecord * epr_read_record (EPR_SDatasetId *dataset_id, uint record_index, EPR_SRecord *record)

Reads a record of a dataset specified by dataset_id.

void epr_free_record (EPR_SRecord *record)

Frees the memory allocated through the given record.

const EPR_SField * epr_get_field (const EPR_SRecord *record, const char *field_name)

Gets a field from the given record.

uint epr_get_num_fields (const EPR_SRecord *record)

Gets the number of fields contained in the given record.

const EPR_SField * epr_get_field_at (const EPR_SRecord *record, uint field_index)

Gets a field at the specified position within the record.

const char * epr_get_field_unit (const EPR_SField *field)

Gets the unit of the field.

const char * epr_get_field_description (const EPR_SField *field)

Gets the description of the field.

uint epr_get_field_num_elems (const EPR_SField *field)

Gets the number of elements of the field.

const char * epr_get_field_name (const EPR_SField *field)

Gets the name of the field.

EPR_EDataTypeId epr_get_field_type (const EPR_SField *field)

Gets the type of the field.

EPR_SRaster * epr_create_compatible_raster (EPR_SBandId *band_id, uint source_width, uint source_height, uint source_step_x, uint source_step_y)

Creates a raster which is compatible with the data type contained in the band identified by band_id.

EPR_SRaster * epr_create_raster (EPR_EDataTypeId data_type, uint source_width, uint source_height, uint source_step_x, uint source_step_y)

Creates a raster of the specified data type.

EPR_SRaster * epr_create_bitmask_raster (uint source_width, uint source_height, uint source_step_x, uint source_step_y)

Creates a raster to be used for reading bitmasks.

int epr_read_band_raster (EPR_SBandId *band_id, int offset_x, int offset_y, EPR_SRaster *raster)

Reads (geo-)physical values of the given band of the specified source-region.

ulong epr_get_raster_elem_size (const EPR_SRaster *raster)

void * epr_get_raster_elem_addr (const EPR_SRaster *raster, ulong offset)

void * epr_get_raster_pixel_addr (const EPR_SRaster *raster, ulong x, ulong y)

void * epr_get_raster_line_addr (const EPR_SRaster *raster, ulong y)

ulong epr_get_raster_width (EPR_SRaster *raster)

Gets the raster's scene width in pixels.

ulong epr_get_raster_height (EPR_SRaster *raster)

Gets the raster's scene height in pixels.

uint epr_get_num_bands (EPR_SProductId *product_id)

Gets the number of all bands contained in a product.

EPR_SBandId * epr_get_band_id_at (EPR_SProductId *product_id, uint index)

Gets the band ID at the specified position within the product.

EPR_SBandId * epr_get_band_id (EPR_SProductId *product_id, const char *band_name)

Gets the band ID corresponding to the specified name.

const char * epr_get_band_name (EPR_SBandId *band_id)

Gets the name of the band for the given band ID.

void epr_free_raster (EPR_SRaster *raster)

Release the memory allocated through a raster.

int epr_read_bitmask_raster (EPR_SProductId *product_id, const char *bm_expr, int offset_x, int offset_y, EPR_SRaster *raster)

Calculates a bit-mask, composed of flags of the given product and combined as described in the given bit-mask expression, for the a certain dimension and sub-sampling as defined in the given raster.

uint epr_get_data_type_size (EPR_EDataTypeId data_type_id)

Gets the size in bytes for an element of the given data type.

const char * epr_data_type_id_to_str (EPR_EDataTypeId data_type_id)

Gets the 'C' data type string for the given data type.

void epr_print_record (const EPR_SRecord *record, FILE *ostream)

This group of functions is for writing an object to a file or standard output.

void epr_print_field (const EPR_SField *field, FILE *ostream)

This group of functions is for writing an object to a file or standard output.

void epr_print_element (const EPR_SRecord *record, uint field_index, uint element_index, FILE *ostream)

This group of functions is for writing an object to a file or standard output.

void epr_dump_record (const EPR_SRecord *record)

This group of functions is for writing an object to a file or standard output.

void epr_dump_field (const EPR_SField *field)

This group of functions is for writing an object to a file or standard output.

void epr_dump_element (const EPR_SRecord *record, uint field_index, uint element_index)

This group of functions is for writing an object to a file or standard output.

char epr_get_field_elem_as_char (const EPR_SField *field, uint elem_index)

This group of functions is for getting the elements of a field as a typed value.

uchar epr_get_field_elem_as_uchar (const EPR_SField *field, uint elem_index)

This group of functions is for getting the elements of a field as a typed value.

short epr_get_field_elem_as_short (const EPR_SField *field, uint elem_index)

This group of functions is for getting the elements of a field as a typed value.

ushort epr_get_field_elem_as_ushort (const EPR_SField *field, uint elem_index)

This group of functions is for getting the elements of a field as a typed value.

long epr_get_field_elem_as_long (const EPR_SField *field, uint elem_index)

This group of functions is for getting the elements of a field as a typed value.

ulong epr_get_field_elem_as_ulong (const EPR_SField *field, uint elem_index)

This group of functions is for getting the elements of a field as a typed value.

float epr_get_field_elem_as_float (const EPR_SField *field, uint elem_index)

This group of functions is for getting the elements of a field as a typed value.

double epr_get_field_elem_as_double (const EPR_SField *field, uint elem_index)

This group of functions is for getting the elements of a field as a typed value.

const EPR_STime * epr_get_field_elem_as_mjd (const EPR_SField *field)

This group of functions is for getting the elements of a field as a typed value.

const char * epr_get_field_elem_as_str (const EPR_SField *field)

This group of functions is for getting the elements of a field as a typed value.

const char * epr_get_field_elems_char (const EPR_SField *field)

This group of functions is for getting an array of field elements of a certain data type.

const uchar * epr_get_field_elems_uchar (const EPR_SField *field)

This group of functions is for getting an array of field elements of a certain data type.

const short * epr_get_field_elems_short (const EPR_SField *field)

This group of functions is for getting an array of field elements of a certain data type.

const ushort * epr_get_field_elems_ushort (const EPR_SField *field)

This group of functions is for getting an array of field elements of a certain data type.

const long * epr_get_field_elems_long (const EPR_SField *field)

This group of functions is for getting an array of field elements of a certain data type.

const ulong * epr_get_field_elems_ulong (const EPR_SField *field)

This group of functions is for getting an array of field elements of a certain data type.

const float * epr_get_field_elems_float (const EPR_SField *field)

This group of functions is for getting an array of field elements of a certain data type.

const double * epr_get_field_elems_double (const EPR_SField *field)

This group of functions is for getting an array of field elements of a certain data type.

uint epr_copy_field_elems_as_doubles (const EPR_SField *field, double *buffer, uint num_elems)

This group of functions is for copying the data of the given field into the given buffer of elements by selected type.

uint epr_copy_field_elems_as_floats (const EPR_SField *field, float *buffer, uint num_elems)

This group of functions is for copying the data of the given field into the given buffer of elements by selected type.

uint epr_copy_field_elems_as_longs (const EPR_SField *field, long *buffer, uint num_elems)

This group of functions is for copying the data of the given field into the given buffer of elements by selected type.

uint epr_copy_field_elems_as_ulongs (const EPR_SField *field, ulong *buffer, uint num_elems)

This group of functions is for copying the data of the given field into the given buffer of elements by selected type.

ulong epr_get_pixel_as_ulong (const EPR_SRaster *raster, int x, int y)

This group of functions is for getting the values of the elements of a raster (i.e.

long epr_get_pixel_as_long (const EPR_SRaster *raster, int x, int y)

This group of functions is for getting the values of the elements of a raster (i.e.

float epr_get_pixel_as_float (const EPR_SRaster *raster, int x, int y)

This group of functions is for getting the values of the elements of a raster (i.e.

double epr_get_pixel_as_double (const EPR_SRaster *raster, int x, int y)

This group of functions is for getting the values of the elements of a raster (i.e.

Define Documentation

#define EPR_PRODUCT_API_NAME_STR "ENVISAT Product Reader API"

#define EPR_PRODUCT_API_VERSION_STR "2.0.5"

#define EPR_MAGIC_PRODUCT_ID 0xCAFFEE64

#define EPR_MAGIC_DATASET_ID 0xEFEABDCA

#define EPR_MAGIC_BAND_ID 0xFEC21ABD

#define EPR_MAGIC_RECORD 0x7BABACAE

#define EPR_MAGIC_FIELD 0xBA0BABBA

#define EPR_MAGIC_RASTER 0x0BABA0EB

#define EPR_MAGIC_FLAG_DEF 0xCABA11AD

#define TRUE 1

#define FALSE 0

#define EPR_PRODUCT_ID_STRLEN 48

Typedef Documentation

typedef enum EPR_DataTypeId EPR_EDataTypeId

typedef enum EPR_ErrCode EPR_EErrCode

typedef enum EPR_LogLevel EPR_ELogLevel

typedef enum EPR_SampleModel EPR_ESampleModel

typedef enum EPR_ScalingMethod EPR_EScalingMethod

typedef struct EPR_ProductId EPR_SProductId

typedef struct EPR_DatasetId EPR_SDatasetId

typedef struct EPR_BandId EPR_SBandId

typedef struct EPR_Record EPR_SRecord

typedef struct EPR_RecordInfo EPR_SRecordInfo

typedef struct EPR_Field EPR_SField

typedef struct EPR_FieldInfo EPR_SFieldInfo

typedef struct EPR_DSD EPR_SDSD

typedef struct EPR_Raster EPR_SRaster

typedef struct EPR_FlagDef EPR_SFlagDef

typedef struct EPR_ParamElem EPR_SParamElem

typedef struct EPR_Time EPR_STime

typedef struct EPR_DatasetRef EPR_SDatasetRef

typedef struct EPR_BitmaskTerm EPR_SBitmaskTerm

typedef struct EPR_FlagSet EPR_SFlagSet

typedef void(* EPR_FErrHandler)(EPR_EErrCode err_code, const char *err_message)

typedef void(* EPR_FLogHandler)(EPR_ELogLevel log_level, const char *log_message)

typedef int boolean

typedef unsigned char uchar

typedef unsigned short ushort

typedef unsigned int uint

typedef unsigned long ulong

typedef long EPR_Magic

Enumeration Type Documentation

enum EPR_DataTypeId

The EPR_DataTypeId enumeration lists all possible data types for field elements in ENVISAT dataset records.

Enumerator:

e_tid_unknown	The ID for unknown types.
e_tid_uchar	An array of unsigned 8-bit integers, C type is `uchar*`.
e_tid_char	An array of signed 8-bit integers, C type is `char*`.
e_tid_ushort	An array of unsigned 16-bit integers, C type is `ushort*`.
e_tid_short	An array of signed 16-bit integers, C type is `short*`.
e_tid_ulong	An array of unsigned 32-bit integers, C type is `ulong*`.
e_tid_long	An array of signed 32-bit integers, C type is `long*`.
e_tid_float	An array of 32-bit floating point numbers, C type is `float*`.
e_tid_double	An array of 64-bit floating point numbers, C type is `double*`.
e_tid_string	A zero-terminated ASCII string, C type is `char*`.
e_tid_spare	An array of unsigned character, C type is `uchar*`.
e_tid_time	A time (MJD) structure, C type is `EPR_Time`.

enum EPR_ErrCode

The EPR_ErrCode enumeration lists all possible error codes for the ENVISAT product reader API.

Enumerator:

e_err_none
e_err_null_pointer
e_err_illegal_arg
e_err_illegal_state
e_err_out_of_memory
e_err_index_out_of_range
e_err_illegal_conversion
e_err_illegal_data_type
e_err_file_not_found
e_err_file_access_denied
e_err_file_read_error
e_err_file_write_error
e_err_file_open_failed
e_err_file_close_failed
e_err_api_not_initialized
e_err_invalid_product_id
e_err_invalid_record
e_err_invalid_band
e_err_invalid_raster
e_err_invalid_dataset_name
e_err_invalid_field_name
e_err_invalid_record_name
e_err_invalid_product_name
e_err_invalid_band_name
e_err_invalid_data_format
e_err_invalid_value
e_err_invalid_keyword_name
e_err_unknown_endian_order
e_err_flag_not_found
e_err_invalid_ddbb_format

enum EPR_LogLevel

The EPR_LogLevel enumeration lists possible log levels for the ENVISAT product reader API.

Enumerator:

e_log_debug
e_log_info
e_log_warning
e_log_error

enum EPR_SampleModel

Enumerator:

e_smod_1OF1
e_smod_1OF2
e_smod_2OF2
e_smod_3TOI
e_smod_2TOF

enum EPR_ScalingMethod

Enumerator:

e_smid_non
e_smid_lin
e_smid_log

Function Documentation

int epr_init_api	(	EPR_ELogLevel	log_level,
		EPR_FLogHandler	log_handler,
		EPR_FErrHandler	err_handler
	)

============================ (1) Initialisation ==========================

Initializes the ENVISAT product reader API.

Parameters:

	log_level	the log level. All logging messages with a log level lower than the given one, will be supressed
	log_handler	the log handler function pointer which will be used for logging, can be `NULL`, if logging shall be disabled
	err_handler	the new error handler (function pointer), can be `NULL`, if errors shall not be reported

Returns:: zero for success, an error code otherwise

Author:: Norman Fomferra

void epr_close_api ( )

Closes the ENVISAT product reader API by releasing all resources allocated by the API.

Author:: Norman Fomferra

int epr_set_log_level ( EPR_ELogLevel log_level )

Sets the log level for the ENVISAT API.

All logging messages with a log level lower than the given one, will be supressed, thus the log handler will not be called for such messages.

Parameters:

log_level

the new log level. All logging messages with a log level lower than the given one, will be supressed

Returns:: zero for success, an error code otherwise

void epr_set_log_handler ( EPR_FLogHandler log_handler )

Sets the log handler for the ENVISAT API.

Parameters:

log_handler

the log handler function pointer which will be used for logging, can be NULL, if logging shall be disabled

See also:: epr_log_message

void epr_log_message	(	EPR_ELogLevel	log_level,
		const char *	log_message
	)

A default implementation for a logging function to be passed into the epr_init() function.

The function writes to stdout, the format is: log_level date time log_message.

Parameters:

	log_level	the log level
	log_message	the log message

void epr_set_err_handler ( EPR_FErrHandler err_handler )

Sets the error handler for the ENVISAT API.

Parameters:

err_handler

the new error handler (function pointer), can be NULL, if errors shall not be reported

EPR_EErrCode epr_get_last_err_code ( )

Gets the error code of the error that occured during the last API function call.

Returns:: the error code, e_err_none or zero if no error occured

const char* epr_get_last_err_message ( )

Gets the error message of the error that occured during the last API function call.

Returns:: the error message, NULL if no error occured

void epr_clear_err ( )

Clears the last error.

After calling this function, calling epr_get_last_err_code returns e_err_none or zero and epr_get_last_err_message returns NULL.

EPR_SProductId* epr_open_product ( const char * product_file_path )

Opens the ENVISAT product file with the given file path,
reads MPH, SPH and all DSDs,
organized the table with parameter of line length and tie points number;
returns a file identifier for the product.

The ENVISAT product reader API must be initialized before.

Parameters:

product_file_path

the path to the ENVISAT product file

Returns:: the product identifier, or NULL if the file could not be opened. epr_get_error_code() should be called in this case in order to obtain the error code.

int epr_close_product ( EPR_SProductId * product_id )

Closes the ENVISAT product file determined by the given product identifier.

Parameters:

product_id the product identifier, if NULL the function immediately returns zero.

Returns:: zero for success, an error code otherwise

ulong epr_get_scene_width ( const EPR_SProductId * product_id )

Gets the product's scene width in pixels.

Parameters:

product_id the product identifier, must not be NULL

Returns:: the product's total scene width in pixels, or 0 if an error occured.

ulong epr_get_scene_height ( const EPR_SProductId * product_id )

Gets the product's scene height in pixels.

Parameters:

product_id the product identifier, must not be NULL

Returns:: the product's total scene height in pixels, or 0 if an error occured.

void epr_print_record	(	const EPR_SRecord *	record,
		FILE *	ostream
	)

This group of functions is for writing an object to a file or standard output.

An object can be

record
field
field element

if FILE* istream is given, the ASCII file will be outputed,
else printed to standard output device.

In case record and/or field:

Parameters:

	record	the record, must not be `NULL`
	field	the field, must not be `NULL`

In case field element:

Parameters:

	record	the record, must not be `NULL`
	field_index	the index of field in the given record
	element_index	the index of element in the given field
	ostream	the identifier of the output file.

void epr_print_field	(	const EPR_SField *	field,
		FILE *	ostream
	)

This group of functions is for writing an object to a file or standard output.

An object can be

record
field
field element

if FILE* istream is given, the ASCII file will be outputed,
else printed to standard output device.

In case record and/or field:

Parameters:

	record	the record, must not be `NULL`
	field	the field, must not be `NULL`

In case field element:

Parameters:

	record	the record, must not be `NULL`
	field_index	the index of field in the given record
	element_index	the index of element in the given field
	ostream	the identifier of the output file.

void epr_print_element	(	const EPR_SRecord *	record,
		uint	field_index,
		uint	element_index,
		FILE *	ostream
	)

This group of functions is for writing an object to a file or standard output.

An object can be

record
field
field element

if FILE* istream is given, the ASCII file will be outputed,
else printed to standard output device.

In case record and/or field:

Parameters:

	record	the record, must not be `NULL`
	field	the field, must not be `NULL`

In case field element:

Parameters:

	record	the record, must not be `NULL`
	field_index	the index of field in the given record
	element_index	the index of element in the given field
	ostream	the identifier of the output file.

void epr_dump_record ( const EPR_SRecord * record )

This group of functions is for writing an object to a file or standard output.

An object can be

record
field
field element

if FILE* istream is given, the ASCII file will be outputed,
else printed to standard output device.

In case record and/or field:

Parameters:

	record	the record, must not be `NULL`
	field	the field, must not be `NULL`

In case field element:

Parameters:

	record	the record, must not be `NULL`
	field_index	the index of field in the given record
	element_index	the index of element in the given field
	ostream	the identifier of the output file.

void epr_dump_field ( const EPR_SField * field )

This group of functions is for writing an object to a file or standard output.

An object can be

record
field
field element

if FILE* istream is given, the ASCII file will be outputed,
else printed to standard output device.

In case record and/or field:

Parameters:

	record	the record, must not be `NULL`
	field	the field, must not be `NULL`

In case field element:

Parameters:

	record	the record, must not be `NULL`
	field_index	the index of field in the given record
	element_index	the index of element in the given field
	ostream	the identifier of the output file.

void epr_dump_element	(	const EPR_SRecord *	record,
		uint	field_index,
		uint	element_index
	)

This group of functions is for writing an object to a file or standard output.

An object can be

record
field
field element

if FILE* istream is given, the ASCII file will be outputed,
else printed to standard output device.

In case record and/or field:

Parameters:

	record	the record, must not be `NULL`
	field	the field, must not be `NULL`

In case field element:

Parameters:

	record	the record, must not be `NULL`
	field_index	the index of field in the given record
	element_index	the index of element in the given field
	ostream	the identifier of the output file.

uint epr_get_num_datasets ( EPR_SProductId * product_id )

Gets the number off all datasets contained in a product.

Parameters:

product_id the product identifier, must not be NULL

Returns:: the number off all dataset

EPR_SDatasetId* epr_get_dataset_id_at	(	EPR_SProductId *	product_id,
		uint	index
	)

Gets the dataset_id at the specified position within the product.

Parameters:

	product_id	the product identifier, must not be `NULL`
	index	the index identifying the position of the dataset, starting with 0, must not be negative

Returns:: the requested dataset_id

EPR_SDatasetId* epr_get_dataset_id	(	EPR_SProductId *	product_id,
		const char *	dataset_name
	)

Gets the dataset_id coresponding to the specified dataset name.

Parameters:

	product_id	the product identifier, must not be `NULL`
	dataset_name	the dataset name, must not be `NULL`

Returns:: the requested dataset_id

const char* epr_get_dataset_name ( EPR_SDatasetId * dataset_id )

Gets the name of the dataset for the given dataset ID.

Parameters:

dataset_id the dataset identifier, must not be NULL

Returns:: the name of the dataset.

const char* epr_get_dsd_name ( const EPR_SDatasetId * dataset_id )

Gets the name of the dsd for the given dataset ID.

Parameters:

dataset_id the dataset identifier, must not be NULL

Returns:: the name of the dsd.

EPR_SRecord* epr_get_mph ( const EPR_SProductId * product_id )

Gets the MPH record from the given product_id.

Parameters:

product_id the product identifier, must not be NULL

Returns:: the MPH record or NULL if an error occured.

EPR_SRecord* epr_get_sph ( const EPR_SProductId * product_id )

Gets the SPH record from the given product_id.

Parameters:

product_id the product identifier, must not be NULL

Returns:: the SPH record or NULL if an error occured.

const EPR_SDSD* epr_get_dsd ( const EPR_SDatasetId * dataset_id )

Gets the dataset descriptor (DSD) for the dataset specified by dataset_id.

Parameters:

dataset_id the dataset identifier, must not be NULL

Returns:: the pointer at the dsd or NULL if an error occured.

uint epr_get_num_records ( const EPR_SDatasetId * dataset_id )

Gets the number of records of the dataset specified by dataset_id.

Parameters:

dataset_id the dataset identifier, must not be NULL

Returns:: the number of records or 0 if an error occured.

uint epr_get_num_dsds ( const EPR_SProductId * product_id )

EPR_SDSD* epr_get_dsd_at	(	const EPR_SProductId *	product_id,
		uint	dsd_index
	)

EPR_SRecord* epr_create_record ( EPR_SDatasetId * dataset_id )

Creates a new, empty record with a structure compatible with the dataset specified by dataset_id.

Such a record is typically used in subsequent calls to epr_read_record.

Parameters:

dataset_id the dataset identifier, must not be NULL

Returns:: the new record instance or NULL if an error occured.

EPR_SRecord* epr_read_record	(	EPR_SDatasetId *	dataset_id,
		uint	record_index,
		EPR_SRecord *	record
	)

Reads a record of a dataset specified by dataset_id.

The record is identified through the given dataset identifier and the given zero-based record index. In order to reduce memory reallocation, a record (pre-) created by the function epr_create_record can be passed to this function. Data is then read into this given record. If no record (NULL) is given, the function initiates a new one. In both cases, the record in which the data is read into will be returned.

Parameters:

	dataset_id	the dataset identifier, must not be `NULL`
	record_index	the zero-based record index
	record	a pre-created record to reduce memory reallocation, can be `NULL` to let the function allocate a new record

Returns:: the record in which the data has been read into or NULL if an error occured.

void epr_free_record ( EPR_SRecord * record )

Frees the memory allocated through the given record.

After calling this function the given record pointer becomes invalid and should not be used anymore.

const EPR_SField* epr_get_field	(	const EPR_SRecord *	record,
		const char *	field_name
	)

Gets a field from the given record.

The field is here identified through the given name.
It contains the field info and all corresponding values.

Parameters:

	record	the record identifier, must not be `NULL`
	field_name	the the name of required field, must not be `NULL`.

Returns:: the field or NULL if an error occured.

uint epr_get_num_fields ( const EPR_SRecord * record )

Gets the number of fields contained in the given record.

Parameters:

record the record to be analysed, must not be NULL

Returns:: the fields number or 0 if an error occured.

const EPR_SField* epr_get_field_at	(	const EPR_SRecord *	record,
		uint	field_index
	)

Gets a field at the specified position within the record.

Parameters:

	record	the record from the field shall be returned, must not be `NULL`
	field_index	the zero-based index (position within record) of the field

Returns:: the field or NULL if an error occured.

const char* epr_get_field_unit ( const EPR_SField * field )

Gets the unit of the field.

Parameters:

field the field from which the unit shall be returned, must not be NULL

Returns:: the field unit or NULL if an error occured.

const char* epr_get_field_description ( const EPR_SField * field )

Gets the description of the field.

Parameters:

field field from which the description shall be returned, must not be NULL

Returns:: the field description or NULL if an error occured.

uint epr_get_field_num_elems ( const EPR_SField * field )

Gets the number of elements of the field.

Parameters:

field field to be analysed, must not be NULL

Returns:: the number of elements of the field or 0 if an error occured.

const char* epr_get_field_name ( const EPR_SField * field )

Gets the name of the field.

Parameters:

field field to be analysed, must not be NULL

Returns:: the field name or NULL if an error occured.

EPR_EDataTypeId epr_get_field_type ( const EPR_SField * field )

Gets the type of the field.

Parameters:

field field to be analysed, must not be NULL

Returns:: the field type or 0 if an error occured.

char epr_get_field_elem_as_char	(	const EPR_SField *	field,
		uint	elem_index
	)

This group of functions is for getting the elements of a field as a typed value.