The datatype that stores all of the information about a Parameter. More...

#include <parameter.h>

Collaboration diagram for Parameter:

Public Member Functions
bool	InitParameter (Parameter param_p, const struct ServiceData service_data_p, ParameterType type, const char const name_s, const char const display_name_s, const char const description_s, ParameterLevel level, void(clear_fn)(Parameter param_p), bool(add_values_to_json_fn)(const Parameter param_p, json_t param_json_p, const bool full_definition_flag), struct Parameter (clone_fn)(const Parameter param_p, const struct ServiceData service_data_p), bool(set_value_from_string_fn)(struct Parameter param_p, const char *value_s))
	Allocate a Parameter. More...

void	NullifyParameter (Parameter *param_p)
	Set a given Parameter's member variables to initial empty, NULL or false values. More...

Parameter *	CloneParameter (const Parameter const src_p, const struct ServiceData data_p)
	Clone a Parameter. More...

void	FreeParameter (Parameter *param_p)
	Free a Parameter. More...

void	ClearParameter (Parameter *param_p)
	Clear a Parameter. More...

const char *	CheckForSignedReal (const Parameter const parameter_p, const void value_p)
	Check whether the value of a Parameter is a non-negative real value. More...

const char *	CheckForNotNull (const Parameter const parameter_p, const void value_p)
	Check whether the value of a Parameter is not `NULL`. More...

bool	AddParameterKeyStringValuePair (Parameter const parameter_p, const char key_s, const char *value_s)
	Add a key value pair to a Parameter. More...

void	RemoveParameterKeyValuePair (Parameter const parameter_p, const char key_s)
	Remove a key value pair from a Parameter. More...

const char *	GetParameterKeyValue (const Parameter const parameter_p, const char key_s)
	Get a value from a Parameter. More...

json_t *	GetParameterAsJSON (const Parameter const parameter_p, const SchemaVersion const sv_p, const bool full_definition_flag)
	Get the json-based representation of a Parameter. More...

Parameter *	CreateParameterFromJSON (const json_t const root_p, struct Service service_p, const bool concise_flag)
	Create a Parameter from a json-based representation. More...

bool	IsJSONParameterConcise (const json_t *const json_p)
	Does the JSON fragment describe a full set of a Parameter's features or just enough to get its current value. More...

const char *	GetUIName (const Parameter *const parameter_p)
	Get the name to use for a Client to use for this Parameter. More...

char *	GetParameterValueAsString (const Parameter const param_p, bool alloc_flag_p)
	Get the current value of a Parameter as a string. More...

bool	SetParameterCurrentValueFromString (Parameter const param_p, const char value_s)
	Set the current value of a Parameter from a string. More...

bool	AddRemoteDetailsToParameter (Parameter param_p, const char const uri_s, const char *const name_s)
	Create a RemoteParameterDetails and add it to the given Parameter. More...

bool	CopyRemoteParameterDetails (const Parameter const src_param_p, Parameter dest_param_p)
	Make a deep copy of all of the RemoteParameterDetails stored on one Parameter to another. More...

bool	GetParameterDescriptionFromConfig (const struct ServiceData service_data_p, const char param_name_s, char **description_ss)
	Get the configured description for a given Parameter. More...

bool	GetParameterDisplayNameFromConfig (const struct ServiceData service_data_p, const char param_name_s, char **display_name_ss)
	Get the configured display name for a given Parameter. More...

bool	GetParameterLevelFromConfig (const struct ServiceData service_data_p, const char param_name_s, ParameterLevel *level_p)
	Get the configured ParameterLevel for a given Parameter. More...

const char *	GetParameterLevelAsString (const ParameterLevel level)
	Get the string representation of a given ParameterLevel. More...

bool	GetParameterLevelFromString (const char level_s, ParameterLevel level_p)
	Get the ParameterLevel from a string representation. More...

ParameterNode *	AllocateParameterNode (Parameter *param_p)
	Allocate a ParameterNode for a given Parameter so that it can be stored upon a LinkedList. More...

void	FreeParameterNode (ListItem *node_p)
	Free a ParameterNode. More...

json_t *	GetRunnableParameterAsJSON (const Parameter param_p, const SchemaVersion const sv_p, const bool full_definition_flag)
	Get the minimal json-based representation of a Parameter needed to run one or more ServiceJobs. More...

Data Fields
ParameterType	pa_type
	The type of the parameter. More...

char *	pa_name_s
	The name of the parameter. More...

char *	pa_display_name_s
	An optional user-friendly name of the parameter to use for client user interfaces. More...

char *	pa_description_s
	The description for this parameter. More...

LinkedList *	pa_options_p
	If the parameter can only take one of a constrained set of values, this will be a LinkedList of ParameterOptionNodes of the possible options. More...

ParameterLevel	pa_level
	The level of the parameter. More...

HashTable *	pa_store_p
	A map allowing the Parameter to store an arbitrary set of key-value pairs. More...

struct ParameterGroup *	pa_group_p
	The ParameterGroup to which this Parameter belongs. More...

LinkedList *	pa_remote_parameter_details_p
	A LinkedList of RemoteParameterNodes that hold the information for Parameters for PairedServices to the Service that owns this Parameter. More...

bool	pa_visible_flag
	Should this Parameter be displayed to the user or is it a hidden variable. More...

bool	pa_refresh_service_flag
	When the value of this Parameter is changed in the client, should it make a request to the server to refresh the service definition? More...

bool	pa_required_flag
	Must this Parameter contain a valid value or can it be empty? More...

void(*	pa_clear_fn )(struct Parameter *param_p)

bool(*	pa_add_values_to_json_fn )(const struct Parameter param_p, json_t param_json_p, const bool full_definition_flag)

struct Parameter (	pa_clone_fn )(const struct Parameter param_p, const struct ServiceData data_p)

bool(*	pa_set_value_from_string_fn )(struct Parameter param_p, const char value_s)

bool	pa_read_only_flag
	Is the Parameter read-only? More...

Detailed Description

The datatype that stores all of the information about a Parameter.

A Parameter stores all of the information required for a Service or Client to set or get the information required for a settable option. This includes a name, description, the datatype of this parameter and much more. The Parameter can also hold arbitrary key-value pairs of char * for extra information if needed.

Member Function Documentation

◆ InitParameter()

bool InitParameter	(	Parameter *	param_p,
		const struct ServiceData *	service_data_p,
		ParameterType	type,
		const char *const	name_s,
		const char *const	display_name_s,
		const char *const	description_s,
		ParameterLevel	level,
		void()(Parameter param_p)	clear_fn,
		bool()(const Parameter param_p, json_t *param_json_p, const bool full_definition_flag)	add_values_to_json_fn,
		struct Parameter ()(const Parameter param_p, const struct ServiceData service_data_p)	clone_fn,
		bool()(struct Parameter param_p, const char *value_s)	set_value_from_string_fn
	)

Allocate a Parameter.

Parameters

service_data_p	The ServiceData for the Service that is allocating this Parameter.
type	The ParameterType for this Parameter.
name_s	The name of the Parameter. The Parameter will store a copy of this string so this value does not need to remain in scope.
display_name_s	An optional name to display for the Parameter for use in Clients. The Parameter will store a copy of this string so this value does not need to remain in scope. This can be `NULL`.
description_s	The description of the Parameter. The Parameter will store a copy of this string so this value does not need to remain in scope.
options_p	This can be used to constrain the Parameter to a fixed set of values. If this is `NULL` then the Parameter can be set to any value.
default_value	The default value for this Parameter.
current_value_p	If this is not `NULL`, then copy this value as the current value of the Parameter. If this is `NULL`, then current value for this Parameter will be set to be a copy of its default value.
bounds_p	If this is not `NULL`, then this will be used to specify the minimum and maximum values that this Parameter can take. If this is `NULL`, then the Parameter can take any value.
level	The ParameterLevel for this Parameter. This determines when the Client should display this Parameter to the user.
check_value_fn	If this is not `NULL`, then this will be used to check whether the Parameter has been set to a valid value.

Returns: A newly-allocated Parameter or NULL upon error.

◆ NullifyParameter()

void NullifyParameter ( Parameter * param_p )

Set a given Parameter's member variables to initial empty, NULL or false values.

This is used for the different types of Parameters to initialise the base Parameter values.

Parameters

param_p The Parameter to initialise.

◆ CloneParameter()

Parameter * CloneParameter	(	const Parameter *const	src_p,
		const struct ServiceData *	data_p
	)

Clone a Parameter.

Parameters

src_p The Parameter to clone.

Returns: A newly-allocated Parameter or NULL upon error.

◆ FreeParameter()

void FreeParameter ( Parameter * param_p )

Free a Parameter.

Parameters

param_p The Parameter to free.

◆ ClearParameter()

void ClearParameter ( Parameter * param_p )

Clear a Parameter.

Parameters

param_p The Parameter to clear.

◆ CheckForSignedReal()

const char * CheckForSignedReal	(	const Parameter *const	parameter_p,
		const void *	value_p
	)

Check whether the value of a Parameter is a non-negative real value.

Parameters

parameter_p	The Parameter to check.
value_p	The value to check.

Returns: An error message string on failure or NULL if the value is a non-negative real number.

◆ CheckForNotNull()

const char * CheckForNotNull	(	const Parameter *const	parameter_p,
		const void *	value_p
	)

Check whether the value of a Parameter is not NULL.

Parameters

parameter_p	The Parameter to check.
value_p	The value to check.

Returns: An error message string on failure or NULL if the value is a not NULL.

◆ AddParameterKeyStringValuePair()

bool AddParameterKeyStringValuePair	(	Parameter *const	parameter_p,
		const char *	key_s,
		const char *	value_s
	)

Add a key value pair to a Parameter.

Parameters

parameter_p	The Parameter to update.
key_s	The key to add to the Parameter. A deep copy of this will be made by the Parameter so the value passed in can go out of scope withut issues. can go out of scope
value_s	The value to add to the Parameter. A deep copy of this will be made by the Parameter so the value passed in can go out of scope withut issues.

Returns: true if the Parameter was updated successfully, false otherwise.

◆ RemoveParameterKeyValuePair()

void RemoveParameterKeyValuePair	(	Parameter *const	parameter_p,
		const char *	key_s
	)

Remove a key value pair from a Parameter.

Parameters

parameter_p	The Parameter to update.
key_s	The key to remove from the Parameter. Its associated value will also be removed.

◆ GetParameterKeyValue()

const char * GetParameterKeyValue	(	const Parameter *const	parameter_p,
		const char *	key_s
	)

Get a value from a Parameter.

Parameters

parameter_p	The Parameter to query.
key_s	The key used to get the associated value from the Parameter.

Returns: The matching value or NULL if the key did not exist for the Parameter.

◆ GetParameterAsJSON()

json_t * GetParameterAsJSON	(	const Parameter *const	parameter_p,
		const SchemaVersion *const	sv_p,
		const bool	full_definition_flag
	)

Get the json-based representation of a Parameter.

Parameters

parameter_p	The Parameter to get.
sv_p	If you wish to create a JSON fragment for a different version of the Grassroots system, then you can set this value to the version that you require. If this is `NULL`, then the current version of the running Grassroots system will be used.
full_definition_flag	If this is `true` then all of the details for this Parameter will get added. If this is `false` then just the name and current value will get added. This is useful is you just want to send the values to use when running a service.

Returns: A newly-allocated json-based description of the Parameter or NULL upon error. When you no longer require the value you need to call json_decref upon it.

See also: GetRunnableParameterAsJSON

◆ CreateParameterFromJSON()

Parameter * CreateParameterFromJSON	(	const json_t *const	root_p,
		struct Service *	service_p,
		const bool	concise_flag
	)

Create a Parameter from a json-based representation.

Parameters

json_p	The json-based decription of the Parameter.
concise_flag	If this is `true`, then just the Parameter values that are needed to run the Service are added. If this is `false` then user-facing attributes such as description, parameter level, group, etc. will be added.

Returns: A newly-allocated Parameter derived from the json-based description or NULL upon error.

◆ IsJSONParameterConcise()

bool IsJSONParameterConcise ( const json_t *const json_p )

Does the JSON fragment describe a full set of a Parameter's features or just enough to get its current value.

Parameters

json_p The JSON fragment

Returns: true if the JSON fragment contains only enough data to get the current value of the Parameter. If the fragment contains data such as the display name, description, etc. then this will return false.

◆ GetUIName()

const char * GetUIName ( const Parameter *const parameter_p )

Get the name to use for a Client to use for this Parameter.

Parameters

parameter_p The Parameter to get the value for.

Returns: The Parameter's display name if it is not NULL, else the Parameter's name.

◆ GetParameterValueAsString()

char * GetParameterValueAsString	(	const Parameter *const	param_p,
		bool *	alloc_flag_p
	)

Get the current value of a Parameter as a string.

Parameters

param_p	The Parameter to get the current value for.
alloc_flag_p	If the returned value had to be newly created, for example if the type of this Parameter is a number, then this will be set to `true` and the returned value will need to be freed using FreeCopiedString to avoid a memory leak. If this is `false` then the returned value points directly to a string within the Parameter's current value.

Returns: The Parameter value as a string or NULL if there was an error.

See also: FreeCopiedString; SetParameterValueFromString

◆ SetParameterCurrentValueFromString()

bool SetParameterCurrentValueFromString	(	Parameter *const	param_p,
		const char *	value_s
	)

Set the current value of a Parameter from a string.

Parameters

param_p	The Parameter to set the current value for.
value_s	The Parameter value as a string.

Returns: true if the Paremeter value was set successfully, false otherwise.

See also: GetParameterValueAsString

◆ AddRemoteDetailsToParameter()

bool AddRemoteDetailsToParameter	(	Parameter *	param_p,
		const char *const	uri_s,
		const char *const	name_s
	)

Create a RemoteParameterDetails and add it to the given Parameter.

Parameters

param_p	The Parameter to add the new RemoteParameterDetails to.
uri_s	The URI of the ExternalServer that runs the PairedService that this RemoteParameter belongs to.
name_s	The name of this Parameter on the PairedService.

Returns: true if the RemoteParameterDetails was added successfully or false otherwise.

See also: AllocateRemoteParameterDetails

◆ CopyRemoteParameterDetails()

bool CopyRemoteParameterDetails	(	const Parameter *const	src_param_p,
		Parameter *	dest_param_p
	)

Make a deep copy of all of the RemoteParameterDetails stored on one Parameter to another.

Parameters

src_param_p	The Parameter to copy of all of the RemoteParameterDetails from.
dest_param_p	The Parameter to copy of all of the RemoteParameterDetails to.

Returns: true if the RemoteParameterDetails was copied successfully or false otherwise.

◆ GetParameterDescriptionFromConfig()

bool GetParameterDescriptionFromConfig	(	const struct ServiceData *	service_data_p,
		const char *	param_name_s,
		char **	description_ss
	)

Get the configured description for a given Parameter.

Parameters

service_data_p	The ServiceData for the Service that the given ParameterGroup belongs to.
param_name_s	The name of the Parameter to check.
description_ss	Pointer to where the value for configured default value for the given Parameter will be stored.

Returns: true if the description was set successfully, false otherwise.

◆ GetParameterDisplayNameFromConfig()

bool GetParameterDisplayNameFromConfig	(	const struct ServiceData *	service_data_p,
		const char *	param_name_s,
		char **	display_name_ss
	)

Get the configured display name for a given Parameter.

Parameters

service_data_p	The ServiceData for the Service that the given ParameterGroup belongs to.
param_name_s	The name of the Parameter to check.
display_name_ss	Pointer to where the value for configured default value for the given Parameter will be stored.

Returns: true if the description was set successfully, false otherwise.

◆ GetParameterLevelFromConfig()

bool GetParameterLevelFromConfig	(	const struct ServiceData *	service_data_p,
		const char *	param_name_s,
		ParameterLevel *	level_p
	)

Get the configured ParameterLevel for a given Parameter.

Parameters

service_data_p	The ServiceData for the Service that the given ParameterGroup belongs to.
param_name_s	The name of the Parameter to check.
level_p	Pointer to where the value for configured ParameterLevel of the given Parameter will be stored.

Returns: true if the ParameterLevel was set successfully, false otherwise.

◆ GetParameterLevelAsString()

const char * GetParameterLevelAsString ( const ParameterLevel level )

Get the string representation of a given ParameterLevel.

Parameters

level The ParameterLevel to get the string representation for. will be stored.

Returns: The string or NULL upon error.

◆ GetParameterLevelFromString()

bool GetParameterLevelFromString	(	const char *	level_s,
		ParameterLevel *	level_p
	)

Get the ParameterLevel from a string representation.

Parameters

level_s	The string representation of the ParameterLevel
level	The ParameterLevel which will be set.

Returns: code>true if the ParameterLevel was set successfully, false otherwise.

◆ AllocateParameterNode()

ParameterNode * AllocateParameterNode ( Parameter * param_p )

Allocate a ParameterNode for a given Parameter so that it can be stored upon a LinkedList.

Parameters

param_p The Parameter that the ParameterNode will reference.

Returns: the newly-allocated ParameterNode or NULL upon error.

◆ FreeParameterNode()

void FreeParameterNode ( ListItem * node_p )

Free a ParameterNode.

Parameters

node_p The ParameterNode to free. ,

◆ GetRunnableParameterAsJSON()

json_t * GetRunnableParameterAsJSON	(	const Parameter *	param_p,
		const SchemaVersion *const	sv_p,
		const bool	full_definition_flag
	)

Get the minimal json-based representation of a Parameter needed to run one or more ServiceJobs.

This is typically used when sending a request to a Server to run a Service.

Parameters

name_s	The name of the Parameter.
value_p	The SharedValue containing the current value of the Parameter.
param_type	The ParameterType of the Parameter.
sv_p	If you wish to create a JSON fragment for a different version of the Grassroots system, then you can set this value to the version that you require. If this is `NULL`, then the current version of the running Grassroots system will be used.
full_definition_flag	If this is `true` then all of the details for this Parameter will get added. If this is `false` then just the name and current value will get added. This is useful is you just want to send the values to use when running a service.

Returns: A newly-allocated json-based description of the Parameter or NULL upon error. When you no longer require the value you need to call json_decref upon it.

See also: GetParameterAsJSON

Field Documentation

◆ pa_type

ParameterType pa_type

The type of the parameter.

◆ pa_name_s

char* pa_name_s

The name of the parameter.

◆ pa_display_name_s

char* pa_display_name_s

An optional user-friendly name of the parameter to use for client user interfaces.

◆ pa_description_s

char* pa_description_s

The description for this parameter.

◆ pa_options_p

LinkedList* pa_options_p

If the parameter can only take one of a constrained set of values, this will be a LinkedList of ParameterOptionNodes of the possible options.

If it's NULL, then any value can be taken.

◆ pa_level

ParameterLevel pa_level

The level of the parameter.

◆ pa_store_p

HashTable* pa_store_p

A map allowing the Parameter to store an arbitrary set of key-value pairs.

Both the keys and values are char *.

◆ pa_group_p

struct ParameterGroup* pa_group_p

The ParameterGroup to which this Parameter belongs.

If this Parameter is not in a ParameterGroup, then this will be NULL

◆ pa_remote_parameter_details_p

LinkedList* pa_remote_parameter_details_p

A LinkedList of RemoteParameterNodes that hold the information for Parameters for PairedServices to the Service that owns this Parameter.

◆ pa_visible_flag

bool pa_visible_flag

Should this Parameter be displayed to the user or is it a hidden variable.

◆ pa_refresh_service_flag

bool pa_refresh_service_flag

When the value of this Parameter is changed in the client, should it make a request to the server to refresh the service definition?

This is analagous to the javascript onchange() event.

◆ pa_required_flag

bool pa_required_flag

Must this Parameter contain a valid value or can it be empty?

◆ pa_clear_fn

void(* pa_clear_fn) (struct Parameter *param_p)

◆ pa_add_values_to_json_fn

bool(* pa_add_values_to_json_fn) (const struct Parameter *param_p, json_t *param_json_p, const bool full_definition_flag)

◆ pa_clone_fn

struct Parameter*(* pa_clone_fn) (const struct Parameter *param_p, const struct ServiceData *data_p)

◆ pa_set_value_from_string_fn

bool(* pa_set_value_from_string_fn) (struct Parameter *param_p, const char *value_s)

◆ pa_read_only_flag

bool pa_read_only_flag

Is the Parameter read-only?

The documentation for this struct was generated from the following file:

parameter.h

Public Member Functions

Data Fields

Detailed Description

Member Function Documentation

◆ InitParameter()

◆ NullifyParameter()

◆ CloneParameter()

◆ FreeParameter()

◆ ClearParameter()

◆ CheckForSignedReal()

◆ CheckForNotNull()

◆ AddParameterKeyStringValuePair()

◆ RemoveParameterKeyValuePair()

◆ GetParameterKeyValue()

◆ GetParameterAsJSON()

◆ CreateParameterFromJSON()

◆ IsJSONParameterConcise()

◆ GetUIName()

◆ GetParameterValueAsString()

◆ SetParameterCurrentValueFromString()

◆ AddRemoteDetailsToParameter()

◆ CopyRemoteParameterDetails()

◆ GetParameterDescriptionFromConfig()

◆ GetParameterDisplayNameFromConfig()

◆ GetParameterLevelFromConfig()

◆ GetParameterLevelAsString()

◆ GetParameterLevelFromString()

◆ AllocateParameterNode()

◆ FreeParameterNode()

◆ GetRunnableParameterAsJSON()

Field Documentation

◆ pa_type

◆ pa_name_s

◆ pa_display_name_s

◆ pa_description_s

◆ pa_options_p

◆ pa_level

◆ pa_store_p

◆ pa_group_p

◆ pa_remote_parameter_details_p

◆ pa_visible_flag

◆ pa_refresh_service_flag

◆ pa_required_flag

◆ pa_clear_fn

◆ pa_add_values_to_json_fn

◆ pa_clone_fn

◆ pa_set_value_from_string_fn

◆ pa_read_only_flag