param_value.h File Reference

#include <stddef.h>

Go to the source code of this file.

Typedefs
typedef struct PARAM_VAL_st	PARAM_VAL

Enumerations
enum	PST_PRIORITY_enum {   PST_PRIORITY_NOTDEFINED = -4, PST_PRIORITY_HIGHEST = -3, PST_PRIORITY_LOWEST = -2, PST_PRIORITY_NONE = -1,   PST_PRIORITY_COUNT = 0xffff, PST_PRIORITY_VALID_BASE = 0, PST_PRIORITY_VALID_ROOF = PST_PRIORITY_VALID_BASE + PST_PRIORITY_COUNT - 1, PST_PRIORITY_HIGHER_THAN = PST_PRIORITY_VALID_ROOF + 1,   PST_PRIORITY_LOWER_THAN = PST_PRIORITY_HIGHER_THAN + PST_PRIORITY_COUNT, PST_PRIORITY_FIELD_OUT_OF_RANGE = PST_PRIORITY_LOWER_THAN + PST_PRIORITY_COUNT }
enum	PST_INDEX_enum { PST_INDEX_LAST = -1, PST_INDEX_FIRST = 0 }

Functions
int	PARAM_VAL_new (const char *value, const char *source, int priority, PARAM_VAL **newObj)
int	PARAM_VAL_insert (PARAM_VAL *target, const char *source, int priority, int at, PARAM_VAL *obj)
void	PARAM_VAL_free (PARAM_VAL *rootValue)
int	PARAM_VAL_getElement (PARAM_VAL *rootValue, const char *source, int priority, int at, PARAM_VAL **val)
int	PARAM_VAL_popElement (PARAM_VAL **rootValue, const char *source, int priority, int at, PARAM_VAL **val)
int	PARAM_VAL_extract (PARAM_VAL *rootValue, const char **value, const char **source, int *priority)
int	PARAM_VAL_getElementCount (PARAM_VAL *rootValue, const char *source, int prio, int *count)
int	PARAM_VAL_getInvalidCount (PARAM_VAL *rootValue, const char *source, int prio, int *count)
int	PARAM_VAL_getPriority (PARAM_VAL *rootValue, int current, int *nextPrio)
int	PARAM_VAL_getErrors (PARAM_VAL *rootValue, int *format, int *content)
int	PARAM_VAL_getInvalid (PARAM_VAL *rootValue, const char *source, int priority, int at, PARAM_VAL **val)
char *	PARAM_VAL_toString (const PARAM_VAL *value, char *buf, size_t buf_len)

Typedef Documentation

PARAM_VAL

typedef struct PARAM_VAL_st PARAM_VAL

Parameter value object. Holds values in list in the order of insertion. Values can be filtered with constraints - source, priority and index. Values are held in linked list.

Enumeration Type Documentation

PST_INDEX_enum

enum PST_INDEX_enum

List of special index macros used for filtering the parameter values.

Enumerator
PST_INDEX_LAST	Returns the last value found with specified constraints.
PST_INDEX_FIRST	Returns the first value found with specified constraints.

PST_PRIORITY_enum

enum PST_PRIORITY_enum

List of priority constraints used for filtering the parameter values.

Enumerator
PST_PRIORITY_NOTDEFINED	Priority equal or less than this value is undefined.
PST_PRIORITY_HIGHEST	Priority for the most significant priority level.
PST_PRIORITY_LOWEST	Priority for the least significant priority level.
PST_PRIORITY_NONE	Priority level is not used when filtering elements.
PST_PRIORITY_COUNT	Count of possible priority values beginning from PST_PRIORITY_VALID_BASE.
PST_PRIORITY_VALID_BASE	The valid base for priority level.
PST_PRIORITY_VALID_ROOF	The valid highest priority level.
PST_PRIORITY_HIGHER_THAN	Extract values higher than A, use priority A + PST_PRIORITY_HIGHER_THAN
PST_PRIORITY_LOWER_THAN	Extract values lower than A, use priority A + PST_PRIORITY_LOWER_THAN
PST_PRIORITY_FIELD_OUT_OF_RANGE	Priorities greater than that are all invalid.

Function Documentation

PARAM_VAL_extract()

int PARAM_VAL_extract	(	PARAM_VAL *	rootValue,
		const char **	value,
		const char **	source,
		int *	priority
	)

Gets the PARAM_VAL data fields.

Parameters

rootValue	PARAM_VAL object.
value	Pointer to receiving pointer to value. Can be NULL.
source	Pointer to receiving pointer to source. Can be NULL.
priority	Pointer to integer where the priority is written. Can be NULL.

Returns

PST_OK when successful, error code otherwise.

PARAM_VAL_free()

void PARAM_VAL_free

(

PARAM_VAL *

rootValue

)

Free parameter value object.

Parameters

rootValue

The first PARAM_VAL link in the linked list.

PARAM_VAL_getElement()

int PARAM_VAL_getElement	(	PARAM_VAL *	rootValue,
		const char *	source,
		int	priority,
		int	at,
		PARAM_VAL **	val
	)

Extracts element from PARAM_VAL list. Element is extracted from given priority level at the given index. If at is PST_INDEX_LAST, the last element is extracted. If priority is PST_PRIORITY_NONE, every element is counted and returned at given index. If priority is PST_PRIORITY_VALID_BASE (0) or higher, only elements at the given priority are counted and extracted. For example, if list contains 2 lower priority values followed by higher priority value at position 3 and at is 0, function returns the last value (but the first value matching the priority). Priority PST_PRIORITY_LOWEST and PST_PRIORITY_HIGHEST are used to extract only the lowest and the highest priority values. Use PST_PRIORITY_HIGHER_THAN + priority or PST_PRIORITY_LOWER_THAN + priority to extract values with higher or lower priority accordingly.

Parameters

rootValue	The first PARAM_VAL link in the linked list.
source	Constraint for the source.
priority	Constraint for the priority.
at	Parameter index in the matching set composed with the constraints.
val	Pointer to receiving pointer.

Returns

PST_OK when successful, error code otherwise. Some more common error codes: PST_INVALID_ARGUMENT and PST_PARAMETER_VALUE_NOT_FOUND.

PARAM_VAL_getElementCount()

int PARAM_VAL_getElementCount	(	PARAM_VAL *	rootValue,
		const char *	source,
		int	prio,
		int *	count
	)

Counts the values with given constraints. If there are no values matching the constraints, 0 is returned.

Parameters

rootValue	The first PARAM_VAL link in the linked list.
source	Constraint for the source.
prio	Constraint for the priority.
count	Pointer to integer receiving the count value.

Returns

PST_OK when successful, error code otherwise.

PARAM_VAL_getErrors()

int PARAM_VAL_getErrors	(	PARAM_VAL *	rootValue,
		int *	format,
		int *	content
	)

Gets the format and content status of PARAM_addValue.

Parameters

rootValue	PARAM_VAL object.
format	Pointer to integer to store the format status.
content	Pointer to integer to store the content status.

Returns

PST_OK when successful, error code otherwise.

See also

PARAM_addValue and PARAM_addControl.

PARAM_VAL_getInvalid()

int PARAM_VAL_getInvalid	(	PARAM_VAL *	rootValue,
		const char *	source,
		int	priority,
		int	at,
		PARAM_VAL **	val
	)

Same as PARAM_VAL_getElement but returns only values with invalid format or content status.

Parameters

rootValue	The first PARAM_VAL link in the linked list.
source	Constraint for the source.
priority	Constraint for the priority.
at	Parameter index in the matching set composed with the constraints.
val	Pointer to receiving pointer.

Returns

PST_OK when successful, error code otherwise. Some more common error codes: PST_INVALID_ARGUMENT and PST_PARAMETER_VALUE_NOT_FOUND.

PARAM_VAL_getInvalidCount()

int PARAM_VAL_getInvalidCount	(	PARAM_VAL *	rootValue,
		const char *	source,
		int	prio,
		int *	count
	)

Counts the invalid values with given constraints. If there are no values matching the constraints, 0 is returned.

Parameters

rootValue	The first PARAM_VAL link in the linked list.
source	Constraint for the source.
prio	Constraint for the priority.
count	Pointer to integer receiving the count value.

Returns

PST_OK when successful, error code otherwise.

PARAM_VAL_getPriority()

int PARAM_VAL_getPriority	(	PARAM_VAL *	rootValue,
		int	current,
		int *	nextPrio
	)

Extracts the next priority level via nextPrio compared with current priority. If current is set to PST_PRIORITY_HIGHEST or PST_PRIORITY_LOWEST the highest or the lowest value is returned. If current is set to other values lower than PST_PRIORITY_VALID_BASE, an error is returned. If current is set to a value that is exactly the priority of the highest value, error code PST_PARAMETER_VALUE_NOT_FOUND is returned, as there is no parameter that has priority level higher that current.

Parameters

rootValue	The first PARAM_VAL link in the linked list.
current	Priority value.
nextPrio	Next highest priority, or the lowest, or the highest.

Returns

PST_OK when successful, error code otherwise.

PARAM_VAL_insert()

int PARAM_VAL_insert	(	PARAM_VAL *	target,
		const char *	source,
		int	priority,
		int	at,
		PARAM_VAL *	obj
	)

Extracts element from target list (see PARAM_VAL_getElement) and inserts obj right after the specified value.

Parameters

target	The first PARAM_VAL link in the linked list.
source	Constraint for the source.
priority	Constraint for the priority.
at	Parameter index in the matching set composed with the constraints.
obj	New obj to be inserted.

Returns

PST_OK when successful, error code otherwise.

PARAM_VAL_new()

int PARAM_VAL_new	(	const char *	value,
		const char *	source,
		int	priority,
		PARAM_VAL **	newObj
	)

Creates a new PARAM_VAL object. If new is pointer to NULL, a new object is created. If new points to existing PARAM_VAL object, a new value is created and appended to the end of the list.

Parameters

value	Value as C-string, can be NULL.
source	Describes the source, e.g. file name or environment variable. Can be NULL.
priority	Priority of the parameter, must be positive.
newObj	Pointer to receiving pointer or pointer to existing value.

Returns

PST_OK when successful, error code otherwise.

Note

The root value must be freed by calling PARAM_VAL_free.

PARAM_VAL_popElement()

int PARAM_VAL_popElement	(	PARAM_VAL **	rootValue,
		const char *	source,
		int	priority,
		int	at,
		PARAM_VAL **	val
	)

Pops an element out of the rootValue and outputs it via val.

Parameters

rootValue	The pointer to pointer to the first PARAM_VAL link in the linked list.
source	Constraint for the source.
priority	Constraint for the priority.
at	Parameter index in the matching set composed with the constraints.
val	Pointer to receiving pointer of popped element.

Returns

PST_OK when successful, error code otherwise.

Attention

After successful popping rootValue will point to the first element in the list. That is, if not the root value link is feed to the function it will be changed to the first element in list.

User is responsible for freeing the object pointed by val.

PARAM_VAL_toString()

char* PARAM_VAL_toString	(	const PARAM_VAL *	value,
		char *	buf,
		size_t	buf_len
	)

Generates PARAM_VAL object description string. Useful for debugging.

Parameters

value	PARAM_VAL object.
buf	Receiving buffer.
buf_len	Receiving buffer size.

Returns

buf if successful, NULL otherwise.