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

#include <parameter.h>

Collaboration diagram for Parameter:
[legend]

Public Member Functions

ParameterAllocateParameter (const struct ServiceData *service_data_p, ParameterType type, bool multi_valued_flag, const char *const name_s, const char *const display_name_s, const char *const description_s, LinkedList *options_p, SharedType default_value, SharedType *current_value_p, ParameterBounds *bounds_p, ParameterLevel level, const char *(*check_value_fn)(const Parameter *const parameter_p, const void *value_p))
 Allocate a Parameter. More...
 
ParameterCloneParameter (const Parameter *const src_p)
 Clone a Parameter. More...
 
void FreeParameter (Parameter *param_p)
 Free 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 SetParameterValue (Parameter *const parameter_p, const void *value_p, const bool current_value_flag)
 Set the current value of a Parameter. More...
 
bool SetParameterValueFromSharedType (Parameter *const parameter_p, const SharedType *src_p, const bool current_value_flag)
 Set the current value of a Parameter from a SharedType. 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...
 
ParameterCreateParameterFromJSON (const json_t *const json_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 SetParameterValueFromString (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 GetParameterDefaultValueFromConfig (const struct ServiceData *service_data_p, const char *param_name_s, const ParameterType pt, SharedType *value_p)
 Get the configured default value for a given Parameter. 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...
 
ParameterNodeAllocateParameterNode (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 char *const name_s, const SharedType *const value_p, const ParameterType param_type, 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...
 
bool CreateAndAddParameterOptionToParameter (Parameter *param_p, SharedType value, const char *const description_s)
 This is a wrapper function to create and add a ParameterOption to a given Parameter. More...
 
LinkedListGetMultiOptions (Parameter *param_p)
 Get the list of ParameterOptions for a given Parameter. More...
 

Data Fields

ParameterType pa_type
 The type of the parameter. More...
 
bool pa_multi_valued_flag
 Does the parameter store multiple values? 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...
 
SharedType pa_default
 The default value for this parameter. More...
 
LinkedListpa_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...
 
ParameterBoundspa_bounds_p
 Does the parameter have any upper or lower limits? More...
 
const char *(* pa_check_value_fn )(const struct Parameter *const parameter_p, const void *value_p)
 Callback function to check whether a particular value is valid for the given parameter. More...
 
ParameterLevel pa_level
 The level of the parameter. More...
 
SharedType pa_current_value
 The current value for this parameter. More...
 
HashTablepa_store_p
 A map allowing the Parameter to store an arbitrary set of key-value pairs. More...
 
struct ParameterGrouppa_group_p
 The ParameterGroup to which this Parameter belongs. More...
 
LinkedListpa_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...
 

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.

Examples
long_running_service.c.

Member Function Documentation

◆ AllocateParameter()

Parameter * AllocateParameter ( const struct ServiceData service_data_p,
ParameterType  type,
bool  multi_valued_flag,
const char *const  name_s,
const char *const  display_name_s,
const char *const  description_s,
LinkedList options_p,
SharedType  default_value,
SharedType current_value_p,
ParameterBounds bounds_p,
ParameterLevel  level,
const char *(*)(const Parameter *const parameter_p, const void *value_p)  check_value_fn 
)

Allocate a Parameter.

Parameters
service_data_pThe ServiceData for the Service that is allocating this Parameter.
typeThe ParameterType for this Parameter.
multi_valued_flagIf this is true then the Parameter can hold multiple values. For single value Parameters, set this to false.
name_sThe 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_sAn 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_sThe description of the Parameter. The Parameter will store a copy of this string so this value does not need to remain in scope.
options_pThis 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_valueThe default value for this Parameter.
current_value_pIf 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_pIf 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.
levelThe ParameterLevel for this Parameter. This determines when the Client should display this Parameter to the user.
check_value_fnIf 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.

◆ CloneParameter()

Parameter * CloneParameter ( const Parameter *const  src_p)

Clone a Parameter.

Parameters
src_pThe Parameter to clone.
Returns
A newly-allocated Parameter or NULL upon error.

◆ FreeParameter()

void FreeParameter ( Parameter param_p)

Free a Parameter.

Parameters
param_pThe Parameter to free.

◆ 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_pThe Parameter to check.
value_pThe 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_pThe Parameter to check.
value_pThe value to check.
Returns
An error message string on failure or NULL if the value is a not NULL.

◆ SetParameterValue()

bool SetParameterValue ( Parameter *const  parameter_p,
const void *  value_p,
const bool  current_value_flag 
)

Set the current value of a Parameter.

Parameters
parameter_pThe Parameter to update.
value_pThe value to update the Parameter to. It will be cast to the appropriate type based upon the Parameter's type.
current_value_flagIf this is true then the current parameter value is the one that will be set. If this is false, then the Parameter's default value will be altered.
Returns
true if the Parameter was updated successfully, false otherwise.

◆ SetParameterValueFromSharedType()

bool SetParameterValueFromSharedType ( Parameter *const  parameter_p,
const SharedType src_p,
const bool  current_value_flag 
)

Set the current value of a Parameter from a SharedType.

Parameters
parameter_pThe Parameter to update.
src_pThe SharedType to update the Parameter from.
current_value_flagIf this is true then the current parameter value is the one that will be set. If this is false, then the Parameter's default value will be altered.
Returns
true if the Parameter was updated successfully, false otherwise.

◆ 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_pThe Parameter to update.
key_sThe 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_sThe 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_pThe Parameter to update.
key_sThe 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_pThe Parameter to query.
key_sThe 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_pThe Parameter to get.
sv_pIf 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_flagIf 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  json_p,
struct Service service_p,
const bool  concise_flag 
)

Create a Parameter from a json-based representation.

Parameters
json_pThe json-based decription of the Parameter.
concise_flagIf 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_pThe 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_pThe 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_pThe Parameter to get the current value for.
alloc_flag_pIf 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

◆ SetParameterValueFromString()

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

Set the current value of a Parameter from a string.

Parameters
param_pThe Parameter to set the current value for.
value_sThe 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_pThe Parameter to add the new RemoteParameterDetails to.
uri_sThe URI of the ExternalServer that runs the PairedService that this RemoteParameter belongs to.
name_sThe 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_pThe Parameter to copy of all of the RemoteParameterDetails from.
dest_param_pThe Parameter to copy of all of the RemoteParameterDetails to.
Returns
true if the RemoteParameterDetails was copied successfully or false otherwise.

◆ GetParameterDefaultValueFromConfig()

bool GetParameterDefaultValueFromConfig ( const struct ServiceData service_data_p,
const char *  param_name_s,
const ParameterType  pt,
SharedType value_p 
)

Get the configured default value for a given Parameter.

Parameters
service_data_pThe ServiceData for the Service that the given ParameterGroup belongs to.
param_name_sThe name of the Parameter to check.
ptThe ParameterType of the given Parameter.
value_pPointer to where the value for configured default value for the given Parameter will be stored.
Returns
true if the default value was set successfully, 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_pThe ServiceData for the Service that the given ParameterGroup belongs to.
param_name_sThe name of the Parameter to check.
description_ssPointer 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_pThe ServiceData for the Service that the given ParameterGroup belongs to.
param_name_sThe name of the Parameter to check.
display_name_ssPointer 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_pThe ServiceData for the Service that the given ParameterGroup belongs to.
param_name_sThe name of the Parameter to check.
level_pPointer to where the value for configured ParameterLevel of the given Parameter will be stored.
Returns
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_pThe 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_pThe ParameterNode to free. ,

◆ GetRunnableParameterAsJSON()

json_t * GetRunnableParameterAsJSON ( const char *const  name_s,
const SharedType *const  value_p,
const ParameterType  param_type,
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_sThe name of the Parameter.
value_pThe SharedValue containing the current value of the Parameter.
param_typeThe ParameterType of the Parameter.
sv_pIf 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_flagIf 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

◆ CreateAndAddParameterOptionToParameter()

bool CreateAndAddParameterOptionToParameter ( Parameter param_p,
SharedType  value,
const char *const  description_s 
)

This is a wrapper function to create and add a ParameterOption to a given Parameter.

It ensures that the options list exists for the Parameter before calling CreateAndAddParameterOption().

Parameters
param_pThe Parameter to add the ParameterOtion to.
valueThe value stored for this ParameterOption.
description_sThe description to show for this ParameterOption.
Returns
true if the ParameterOption was created and added to the Parameter successfully, false otherwise.

◆ GetMultiOptions()

LinkedList * GetMultiOptions ( Parameter param_p)

Get the list of ParameterOptions for a given Parameter.

If the list does not currently exist, then an empty LinkedList will be created and added to the Parameter prior to this function returning.

Parameters
param_pThe Parameter to get the ParameterOptions list from.
Returns
The LinkedList of ParameterOptionNodes or NULL upon error.

Field Documentation

◆ pa_type

ParameterType pa_type

The type of the parameter.

◆ pa_multi_valued_flag

bool pa_multi_valued_flag

Does the parameter store multiple values?

◆ 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_default

SharedType pa_default

The default value for this parameter.

It requires use of pa_type to access the correct value.

◆ 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_bounds_p

ParameterBounds* pa_bounds_p

Does the parameter have any upper or lower limits?

◆ pa_check_value_fn

const char*(* pa_check_value_fn) (const struct Parameter *const parameter_p, const void *value_p)

Callback function to check whether a particular value is valid for the given parameter.

Parameters
parameter_pThe Parameter to check.
value_pPointer to the potential value to check for.
Returns
NULL if the value is valid or an error string if the value is invalid for this Parameter, .

◆ pa_level

ParameterLevel pa_level

The level of the parameter.

◆ pa_current_value

SharedType pa_current_value

The current value for this parameter.

It requires use of pa_type to access the correct value.

◆ 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.


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