Utilities to extract configuration parameters from the file format defined in the E2E-ICD. More...

Modules
	Legacy API
	Deprecated prior version of the ConFM functionality.

Data Structures
struct	osfi_timevalue
	Representation of the value of a TIME parameter. More...

struct	osfi_ownstr_t
	String allocated by OSFI. More...

struct	osfi_ownfile_t
	String allocated by OSFI. More...

struct	osfi_vecInteger_t
	Vector of integer values, with size and contents. More...

struct	osfi_vecDouble_t
	Vector of floating point values, with size and contents. More...

struct	osfi_vecBoolean_t
	Vector of Boolean values, with size and contents. More...

struct	osfi_vecTime_t
	Vector of time values, with size and contents. More...

struct	osfi_vecString_t
	Vector of string values, with size and contents. More...

struct	osfi_vecFile_t
	Vector of file/folder values, with size and contents. More...

struct	osfi_matInteger_t
	Matrix of integer values, with dimension sizes and contents. More...

struct	osfi_matDouble_t
	Matrix of floating point values, with dimension sizes and contents. More...

struct	osfi_matBoolean_t
	Matrix of Boolean values, with dimension sizes and contents. More...

struct	osfi_matTime_t
	Matrix of time values, with dimension sizes and contents. More...

struct	osfi_matString_t
	Matrix of string values, with dimension sizes and contents. More...

struct	osfi_matFile_t
	Matrix of file/folder values, with dimension sizes and contents. More...

Typedefs
typedef struct osfi_paramreader	osfi_paramreader_t
	Opaque type representing an open configuration file.

typedef struct osfi_timevalue	osfi_timevalue_t
	Representation of the value of a TIME parameter. More...

Enumerations
enum	osfi_confm_param_type { OSFI_CONFM_PT_INTEGER = 1 , OSFI_CONFM_PT_DOUBLE , OSFI_CONFM_PT_BOOLEAN , OSFI_CONFM_PT_STRING , OSFI_CONFM_PT_FILE , OSFI_CONFM_PT_FOLDER , OSFI_CONFM_PT_TIME }
	Types of parameter values. More...

enum	osfi_confm_val_res { OSFI_CONFM_VAL_PASSED = 1 , OSFI_CONFM_VAL_INVALID , OSFI_CONFM_VAL_ERRORS }
	Return values for the function that validates a configuration file against a schema. More...

Functions
int	osfiTimevalue_cmp (const osfi_timevalue_t a, const osfi_timevalue_t b)
	Compares two values of a TIME parameter. More...

Basic functionality
Essential routines used to open/close a configuration file and read parameter values. Note The generic parameter value getters osfiConFmParamValue() and osfiConFmParamArrayLeaf() are only available if the library was built with C11 support.
osfi_paramreader_t *	osfiConFmCfgFileOpen (const char *path)
	Parses the configuration file at path and returns a handle to it. More...

void	osfiConFmCfgFileClose (osfi_paramreader_t *pr)
	Closes the configuration file pointed by pr and releases all resources tied to it. More...

#define	osfiConFmParamValue(dest, pr, param)
	Value getter for non-ARRAY parameters. More...

#define	osfiConFmParamArrayLeaf(dest, pr, param, depth, node)
	Value getter for ARRAY parameters. More...

Queries about a configuration file
enum osfi_confm_val_res	osfiConFmValidateSchema (osfi_paramreader_t pr, const char schemaFile)
	Performs validation of the given configuration file against a schema document. More...

bool	osfiConFmParamExists (osfi_paramreader_t pr, const char param)
	Finds a parameter in the given configuration file. More...

bool	osfiConFmGetAllParams (osfi_vecString_t *out, osfi_paramreader_t pr)
	Retrieves the path of every parameter in the given configuration file. More...

bool	osfiConFmGetChildParams (osfi_vecString_t *out, osfi_paramreader_t pr, const char *group)
	Retrieves the path of all parameters that are children of the given group. More...

Non-value queries about a specific parameter
bool	osfiConFmParamIsArray (osfi_paramreader_t pr, const char param)
	Checks if the given parameter is of type ARRAY. More...

bool	osfiConFmParamLocalName (osfi_ownstr_t *out, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamDescription (osfi_ownstr_t *out, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamMinValue (osfi_ownstr_t *out, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamMaxValue (osfi_ownstr_t *out, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamUnits (osfi_ownstr_t *out, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamRawValue (osfi_ownstr_t *out, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamDimensions (osfi_vecInteger_t *out, osfi_paramreader_t pr, const char *param)
	Retrieves the dimensions of the given parameter. More...

enum osfi_confm_param_type	osfiConFmParamElementType (osfi_paramreader_t pr, const char param)
	Returns the value type of the given parameter. More...

bool	osfiConFmParamNodeIsLeaf (osfi_paramreader_t pr, const char param, int depth, const int node[depth])
	Checks whether the given array node in a parameter has no children (is a leaf node). More...

int	osfiConFmParamNodeSize (osfi_paramreader_t pr, const char param, int depth, const int node[depth])
	Returns the number of elements (if a leaf) or children of an array node in a parameter. More...

void	osfiConFmParamPrint (osfi_paramreader_t pr, const char param)
	Writes information about the chosen parameter to the standard output. More...

Typed value getters
Functions to retrieve the value of a parameter, depending on the element and structural type. Note If the library has been built with C11 support, it is much preferable to use the generic functions osfiConFmParamValue() and osfiConFmParamArrayLeaf() instead.
bool	osfiConFmParamValueInteger (int32_t dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamVectorInteger (osfi_vecInteger_t *dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamMatrixInteger (osfi_matInteger_t *dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamArrayLeafInteger (osfi_vecInteger_t *dest, osfi_paramreader_t pr, const char *param, int depth, const int node[depth])

bool	osfiConFmParamValueDouble (double dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamVectorDouble (osfi_vecDouble_t *dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamMatrixDouble (osfi_matDouble_t *dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamArrayLeafDouble (osfi_vecDouble_t *dest, osfi_paramreader_t pr, const char *param, int depth, const int node[depth])

bool	osfiConFmParamValueBoolean (bool dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamVectorBoolean (osfi_vecBoolean_t *dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamMatrixBoolean (osfi_matBoolean_t *dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamArrayLeafBoolean (osfi_vecBoolean_t *dest, osfi_paramreader_t pr, const char *param, int depth, const int node[depth])

bool	osfiConFmParamValueTime (osfi_timevalue_t dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamVectorTime (osfi_vecTime_t *dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamMatrixTime (osfi_matTime_t *dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamArrayLeafTime (osfi_vecTime_t *dest, osfi_paramreader_t pr, const char *param, int depth, const int node[depth])

bool	osfiConFmParamValueString (osfi_ownstr_t *dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamVectorString (osfi_vecString_t *dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamMatrixString (osfi_matString_t *dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamArrayLeafString (osfi_vecString_t *dest, osfi_paramreader_t pr, const char *param, int depth, const int node[depth])

bool	osfiConFmParamValueFile (osfi_ownfile_t *dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamVectorFile (osfi_vecFile_t *dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamMatrixFile (osfi_matFile_t *dest, osfi_paramreader_t pr, const char *param)

bool	osfiConFmParamArrayLeafFile (osfi_vecFile_t *dest, osfi_paramreader_t pr, const char *param, int depth, const int node[depth])

Detailed Description

Utilities to extract configuration parameters from the file format defined in the E2E-ICD.

The configuration files provided by the openSF HMI contain the following elements:

Element (any_tag_name). This element can create nested groups to enclose parameters and provide scope information. Optional element.
Element parameter. The value will be stored as the text content, or as further subelements. The following attributes are defined:
- name. Last part of the parameter identifier. Names cannot contain spaces.
- description. Short definition or meaning for the parameter, optional.
- type. Possible values for this attribute are all the element types defined in the E2E-ICD, plus ARRAY or MATRIX which are special (structural) types. If the latter appear, the actual data type of the parameter is in the elementType attribute.
- units, min, max. Optional metadata for the parameter.
- dims. Size of the dimensions, used to represent vectors and matrices. The first number refers to columns and the second one to rows when describing a matrix. This attribute is also optional: for scalar variables, dims can be avoided.

See the E2E-ICD reference for more details.

Examples: See an usage example here.

Macro Definition Documentation

◆ osfiConFmParamArrayLeaf

#define osfiConFmParamArrayLeaf	(	dest,
		pr,
		param,
		depth,
		node
	)

Value:

    _Generic((dest),\
        osfi_vecInteger_t**: osfiConFmParamArrayLeafInteger,\
        osfi_vecDouble_t**:  osfiConFmParamArrayLeafDouble,\
        osfi_vecBoolean_t**: osfiConFmParamArrayLeafBoolean,\
        osfi_vecTime_t**:    osfiConFmParamArrayLeafTime,\
        osfi_vecString_t**:  osfiConFmParamArrayLeafString,\
        osfi_vecFile_t**:    osfiConFmParamArrayLeafFile\
    )((dest), (pr), (param), (depth), (node))

Value getter for ARRAY parameters.

The call fails and returns false if any of the following applies:

Any argument is a null pointer, or depth is negative.
The parameter does not exist in the configuration file.
The structure type is wrong, or the values cannot be parsed as the requested type.
Allocation of memory for the parsed values fails.

In case of failure, the value of *dest is undefined. Otherwise, *dest is replaced by the value of the parameter, which will be a pointer to memory allocated by OSFI. The lifetime of *dest is tied to that of pr: it will be freed when osfiConFmCfgFileClose() is called on it.

Parameters

[out]	dest	Pointer to the destination object; any value will be replaced.
[in]	pr	Open parameter reader object.
[in]	param	Full path of the parameter.
[in]	depth	Number of indices in (size of) the node argument.
[in]	node	Indices of the leaf node to find.

Returns: true if the operation completed, false if it failed.

◆ osfiConFmParamValue

#define osfiConFmParamValue	(	dest,
		pr,
		param
	)

Value:

    _Generic((dest),\
        int32_t*:            osfiConFmParamValueInteger,\
        double*:             osfiConFmParamValueDouble,\
        bool*:               osfiConFmParamValueBoolean,\
        osfi_timevalue_t*:   osfiConFmParamValueTime,\
        osfi_ownstr_t**:     osfiConFmParamValueString,\
        osfi_ownfile_t**:    osfiConFmParamValueFile,\
        osfi_vecInteger_t**: osfiConFmParamVectorInteger,\
        osfi_vecDouble_t**:  osfiConFmParamVectorDouble,\
        osfi_vecBoolean_t**: osfiConFmParamVectorBoolean,\
        osfi_vecTime_t**:    osfiConFmParamVectorTime,\
        osfi_vecString_t**:  osfiConFmParamVectorString,\
        osfi_vecFile_t**:    osfiConFmParamVectorFile,\
        osfi_matInteger_t**: osfiConFmParamMatrixInteger,\
        osfi_matDouble_t**:  osfiConFmParamMatrixDouble,\
        osfi_matBoolean_t**: osfiConFmParamMatrixBoolean,\
        osfi_matTime_t**:    osfiConFmParamMatrixTime,\
        osfi_matString_t**:  osfiConFmParamMatrixString,\
        osfi_matFile_t**:    osfiConFmParamMatrixFile\
    )((dest), (pr), (param))

Value getter for non-ARRAY parameters.

The call fails and returns false if any of the following applies:

Any argument is a null pointer.
The parameter does not exist in the configuration file.
The structure type is wrong, or the values cannot be parsed as the requested type.
Allocation of memory for the parsed values fails.

In case of failure, the value of *dest is undefined. Otherwise, *dest is replaced by the value of the parameter.

If the type and structure requires it (scalar string/file, or any type of vector or matrix), it will be a pointer to memory allocated by OSFI. In that case, the lifetime of *dest is tied to that of pr, that is, it will be freed when osfiConFmCfgFileClose() is called on it.

Parameters

[out]	dest	Pointer to the destination object; any existing value will be replaced.
[in]	pr	Open parameter reader object.
[in]	param	Full path of the parameter.

Returns: true if the operation completed, false if it failed.

Examples: ConFM.c.

Typedef Documentation

◆ osfi_timevalue_t

typedef struct osfi_timevalue osfi_timevalue_t

Representation of the value of a TIME parameter.

The range of each field is according to the CCSDS ASCII time code "A" format.

Warning: The ranges mentioned here are for exposition only, they are not necessarily checked.

Note: This type is layout-compatible with the OSFI-C++ type osfi::confm::TimeValue.

Enumeration Type Documentation

◆ osfi_confm_param_type

enum osfi_confm_param_type

Types of parameter values.

Enumerator
OSFI_CONFM_PT_INTEGER	Integral number with the value range of its associated type `int32_t`.
OSFI_CONFM_PT_DOUBLE	Floating point number with the range of IEEE754 binary64. Its associated type is `double`. Note This type is named `FLOAT` in the E2E-ICD and in configuration files. It was renamed here to avoid confusion with the C type `float` which is usually less precise.
OSFI_CONFM_PT_BOOLEAN	Truth value, its associated type is `bool`.
OSFI_CONFM_PT_STRING	A string of arbitrary characters. Its associated type is `char*`, although scalars are represented by the osfi_ownstr_t type.
OSFI_CONFM_PT_FILE	Path to a file. If relative, it is resolved against the configured base directory which, following the E2E-ICD, is read from the enviroment variable "E2E_HOME". Its associated type is `char*`, but scalars are represented by the osfi_ownfile_t type.
OSFI_CONFM_PT_FOLDER	Path to a folder, with the same rules and representation as OSFI_CONFM_PT_FILE.
OSFI_CONFM_PT_TIME	Timecode formatted as CCSDS ASCII time format with milli- or micro-second precision. It is represented with the osfi_timevalue_t type. Note Notwithstanding the E2E-ICD, OSFI allows up to nanosecond precision.

◆ osfi_confm_val_res

enum osfi_confm_val_res

Return values for the function that validates a configuration file against a schema.

See also: osfiConFmValidateSchema(); osfiConFMValidateAgainst()

Enumerator
OSFI_CONFM_VAL_PASSED	Validation ran and passed.
OSFI_CONFM_VAL_INVALID	Validation ran but the document did not validate against the schema.
OSFI_CONFM_VAL_ERRORS	Validation failed to run due to any error (e.g. schema not found).

Function Documentation

◆ osfiConFmCfgFileClose()

void osfiConFmCfgFileClose ( osfi_paramreader_t * pr )

Closes the configuration file pointed by pr and releases all resources tied to it.

The released resources include all OSFI-allocated memory for parameter properties and values extracted from the file.

If pr is a null pointer, this call is a no-op. However, calling this function multiple times with the same handle results in undefined behaviour.

Parameters

[in,out] pr Handle returned by osfiConFmCfgFileOpen() and not closed before.

Examples: ConFM.c.

◆ osfiConFmCfgFileOpen()

osfi_paramreader_t* osfiConFmCfgFileOpen ( const char * path )

Parses the configuration file at path and returns a handle to it.

If the argument is NULL, or on any fatal failure that prevents parsing the file, a null pointer is returned. Otherwise, the resulting non-null pointer can be used in other calls to the rest of the ConFM API, and should be closed with osfiConFmCfgFileClose() when done.

Parameters

[in] path Path to an XML file in the E2E-ICD configuration file format.

Returns: OSFI-allocated object representing the file

Examples: ConFM.c.

◆ osfiConFmGetAllParams()

bool osfiConFmGetAllParams	(	osfi_vecString_t **	out,
		osfi_paramreader_t *	pr
	)

Retrieves the path of every parameter in the given configuration file.

Parameters

[out]	out	Pointer to the destination object; any existing value will be replaced.
[in]	pr	Handle of a configuration file.

Returns: true if the operation was successful, false otherwise.

◆ osfiConFmGetChildParams()

bool osfiConFmGetChildParams	(	osfi_vecString_t **	out,
		osfi_paramreader_t *	pr,
		const char *	group
	)

Retrieves the path of all parameters that are children of the given group.

The resulting vector will contain the paths of all parameters that are under group, either directly or indirectly. For example, if group is "a.b", parameters "a.b.c" or "a.b.x.y" will be returned, but parameters "a.b" or "a.bb" will not.

Parameters

[out]	out	Pointer to the destination object; any existing value will be replaced.
[in]	pr	Handle of a configuration file.
[in]	group	Path of a group in the file.

Returns: true if the operation was successful, false otherwise.

◆ osfiConFmParamDimensions()

bool osfiConFmParamDimensions	(	osfi_vecInteger_t **	out,
		osfi_paramreader_t *	pr,
		const char *	param
	)

Retrieves the dimensions of the given parameter.

If any of the arguments are NULL, or if the parameter does not exist, false is returned and *out is not modified. Otherwise, *out is replaced with a pointer to an OSFI-allocated vector containing the sizes of the declared dimensions of the parameter.

Parameters

[out]	out	Pointer to the destination, its value will be replaced.
[in]	pr	Handle of a configuration file.
[in]	param	Path of a parameter in the file.

Returns: true if the operation succeeded, false on any error.

◆ osfiConFmParamElementType()

enum osfi_confm_param_type osfiConFmParamElementType	(	osfi_paramreader_t *	pr,
		const char *	param
	)

Returns the value type of the given parameter.

If any of the inputs are NULL, or if the parameter does not exist, the flag value 0 is returned. Otherwise, the return value corresponds to the declared type of its values.

Parameters

[in]	pr	Handle of a configuration file.
[in]	param	Path of a parameter in the file.

Returns: one of the types in osfi_confm_param_type, or 0 in case of error.

◆ osfiConFmParamExists()

bool osfiConFmParamExists	(	osfi_paramreader_t *	pr,
		const char *	param
	)

Finds a parameter in the given configuration file.

Parameters

[in]	pr	Handle of a configuration file.
[in]	param	Full path of the parameter.

Returns: true if a parameter with that path exists in the file, false otherwise.

◆ osfiConFmParamIsArray()

bool osfiConFmParamIsArray	(	osfi_paramreader_t *	pr,
		const char *	param
	)

Checks if the given parameter is of type ARRAY.

Parameters

[in]	pr	Handle of a configuration file.
[in]	param	Path of a parameter in the file.

Returns: true if the parameter exists and is of type ARRAY, false otherwise.

◆ osfiConFmParamNodeIsLeaf()

bool osfiConFmParamNodeIsLeaf	(	osfi_paramreader_t *	pr,
		const char *	param,
		int	depth,
		const int	node[depth]
	)

Checks whether the given array node in a parameter has no children (is a leaf node).

If any of the inputs are NULL (except node, see below), or if the parameter does not exist, false is returned.

Parameters

[in]	pr	Handle of a configuration file.
[in]	param	Path of a parameter in the file.
[in]	depth	Number of elements of node
[in]	node	Location in the array node tree. May be NULL if depth is 0.

Returns: true iff param exists and the chosen array node has no children, false otherwise.

◆ osfiConFmParamNodeSize()

int osfiConFmParamNodeSize	(	osfi_paramreader_t *	pr,
		const char *	param,
		int	depth,
		const int	node[depth]
	)

Returns the number of elements (if a leaf) or children of an array node in a parameter.

If any of the inputs are NULL (except node, see below), or if the parameter does not exist, 0 is returned. Otherwise, the return value corresponds to the number of elements for a leaf node, or the number of direct children for a non-leaf node.

Parameters

[in]	pr	Handle of a configuration file.
[in]	param	Path of a parameter in the file.
[in]	depth	Number of elements of node
[in]	node	Location in the array node tree. May be NULL if depth is 0.

Returns: Size of the requested node, or 0 on any error condition.

◆ osfiConFmParamPrint()

void osfiConFmParamPrint	(	osfi_paramreader_t *	pr,
		const char *	param
	)

Writes information about the chosen parameter to the standard output.

If any of the inputs are NULL, or if the parameter does not exist, this is a no-op.

Parameters

[in]	pr	Handle of a configuration file.
[in]	param	Path of a parameter in the file.

◆ osfiConFmValidateSchema()

enum osfi_confm_val_res osfiConFmValidateSchema	(	osfi_paramreader_t *	pr,
		const char *	schemaFile
	)

Performs validation of the given configuration file against a schema document.

Parameters

[in]	pr	Handle of a configuration file.
[in]	schemaFile	XSD file to use, or NULL if the schema is referenced in the XML itself.

Returns: result of the validation

Examples: ConFM.c.

◆ osfiTimevalue_cmp()

int osfiTimevalue_cmp	(	const osfi_timevalue_t *	a,
		const osfi_timevalue_t *	b
	)

Parameters

[in] a,b Values to compare. NULL pointers compare as less-than any non-NULL value.

Returns: A negative number if a<b, zero if a==b, a positive number if a>b

Modules

Data Structures

Typedefs

Enumerations

Functions

Basic functionality

Queries about a configuration file

Non-value queries about a specific parameter

Typed value getters

Detailed Description

Macro Definition Documentation

◆ osfiConFmParamArrayLeaf

◆ osfiConFmParamValue

Typedef Documentation

◆ osfi_timevalue_t

Enumeration Type Documentation

◆ osfi_confm_param_type

◆ osfi_confm_val_res

Function Documentation

◆ osfiConFmCfgFileClose()

◆ osfiConFmCfgFileOpen()

◆ osfiConFmGetAllParams()

◆ osfiConFmGetChildParams()

◆ osfiConFmParamDimensions()

◆ osfiConFmParamElementType()

◆ osfiConFmParamExists()

◆ osfiConFmParamIsArray()

◆ osfiConFmParamNodeIsLeaf()

◆ osfiConFmParamNodeSize()

◆ osfiConFmParamPrint()

◆ osfiConFmValidateSchema()

◆ osfiTimevalue_cmp()