ParameterSet Struct Reference

A set of Parameters along with an optional name and description. More...

#include <parameter_set.h>

Collaboration diagram for ParameterSet:
[legend]

Public Member Functions

ParameterSetAllocateParameterSet (const char *name_s, const char *description_s)
 Create a new ParameterSet containing no parameters. More...
 
void FreeParameterSet (ParameterSet *params_p)
 Free a ParameterSet and all of its Parameters. More...
 
bool AddParameterToParameterSet (ParameterSet *params_p, Parameter *param_p)
 Add a Parameter to a ParameterSet. More...
 
ParameterCreateAndAddParameterToParameterSet (const struct ServiceData *service_data_p, ParameterSet *params_p, ParameterGroup *group_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, uint8 level, const char *(*check_value_fn)(const Parameter *const parameter_p, const void *value_p))
 Allocate a new Parameter and add it to a ParameterSet. More...
 
ParameterEasyCreateAndAddParameterToParameterSet (const struct ServiceData *service_data_p, ParameterSet *params_p, ParameterGroup *group_p, ParameterType type, const char *const name_s, const char *const display_name_s, const char *const description_s, SharedType default_value, uint8 level)
 Allocate a new Parameter and add it to a ParameterSet. More...
 
json_t * GetParameterSetAsJSON (const ParameterSet *const param_set_p, const SchemaVersion *const sv_p, const bool full_definition_flag)
 Generate a json-based description of a ParameterSet. More...
 
json_t * GetParameterSetSelectionAsJSON (const ParameterSet *const param_set_p, const SchemaVersion *const sv_p, const bool full_definition_flag, void *data_p, bool(*add_param_fn)(const Parameter *param_p, void *data_p))
 Generate a json-based description of a selection of ParameterSet. More...
 
ParameterSetCreateParameterSetFromJSON (const json_t *const json_p, struct Service *service_p, const bool concise_flag)
 Create a new ParameterSet from a json-based description. More...
 
ParameterGetParameterFromParameterSetByName (const ParameterSet *const params_p, const char *const name_s)
 Get the Parameter with a given name from a ParameterSet. More...
 
ParameterNodeGetParameterNodeFromParameterSetByName (const ParameterSet *const params_p, const char *const name_s)
 Get the ParameterNode for a Parameter with a given name from a ParameterSet. More...
 
bool GetParameterValueFromParameterSet (const ParameterSet *const params_p, const char *const name_s, SharedType *value_p, const bool current_value_flag)
 Get the value of a Parameter within a ParameterSet. More...
 
ParameterDetachParameterByName (ParameterSet *params_p, const char *const name_s)
 Remove the Parameter with a given name from a ParameterSet. More...
 
bool DetachParameter (ParameterSet *params_p, Parameter *param_p)
 Remove the Parameter with from a ParameterSet. More...
 
struct ParameterGroupGetParameterGroupFromParameterSetByGroupName (const ParameterSet *const params_p, const char *const name_s)
 Get all of the Parameters within a given ParameterGroup. More...
 
bool AddParameterGroupToParameterSet (ParameterSet *param_set_p, ParameterGroup *group_p)
 Add a ParameterGroup to a ParameterSet. More...
 

Data Fields

const char * ps_name_s
 An optional name for the ParameterSet. More...
 
const char * ps_description_s
 An optional description for the ParameterSet. More...
 
LinkedListps_params_p
 A LinkedList of ParameterNodes containing the Parameters. More...
 
LinkedListps_grouped_params_p
 A LinkedList of ParameterGroupNodes for this ParameterSet. More...
 

Detailed Description

A set of Parameters along with an optional name and description.

Examples
long_running_service.c.

Member Function Documentation

◆ AllocateParameterSet()

ParameterSet * AllocateParameterSet ( const char *  name_s,
const char *  description_s 
)

Create a new ParameterSet containing no parameters.

Parameters
name_sThe name to use for the ParameterSet.
description_sThe description to use for the ParameterSet.
Returns
The newly created ParameterSet or NULL upon error.
Examples
long_running_service.c.

◆ FreeParameterSet()

void FreeParameterSet ( ParameterSet params_p)

Free a ParameterSet and all of its Parameters.

Parameters
params_pThe ParameterSet to free.
Examples
long_running_service.c.

◆ AddParameterToParameterSet()

bool AddParameterToParameterSet ( ParameterSet params_p,
Parameter param_p 
)

Add a Parameter to a ParameterSet.

Parameters
params_pThe ParameterSet to amend.
param_pThe Parameter to add.
Returns
true if the Parameter was added successfully, false otherwise.

◆ CreateAndAddParameterToParameterSet()

Parameter * CreateAndAddParameterToParameterSet ( const struct ServiceData service_data_p,
ParameterSet params_p,
ParameterGroup group_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,
uint8  level,
const char *(*)(const Parameter *const parameter_p, const void *value_p)  check_value_fn 
)

Allocate a new Parameter and add it to a ParameterSet.

Parameters
service_data_pThe ServiceData for the Service that is allocating this Parameter.
params_pThe ParameterSet to add the new Parameter to.
group_pThe ParameterGroup to add this Parameter to. This can be NULL in which case the Parameter will not be placed within any ParameterGroup.
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_pThe options specifying the possible values that this Parameter can take. If NULL then it can take any valid values for its given ParameterType.
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.

◆ EasyCreateAndAddParameterToParameterSet()

Parameter * EasyCreateAndAddParameterToParameterSet ( const struct ServiceData service_data_p,
ParameterSet params_p,
ParameterGroup group_p,
ParameterType  type,
const char *const  name_s,
const char *const  display_name_s,
const char *const  description_s,
SharedType  default_value,
uint8  level 
)

Allocate a new Parameter and add it to a ParameterSet.

This is suitable for most Parameters that are single-valued. For more complex Parameters, use CreateAndAddParameterToParameterSet.

Parameters
service_data_pThe ServiceData for the Service that is allocating this Parmeter.
params_pThe ParameterSet to add the new Parameter to.
group_pThe ParameterGroup to add this Parameter to. This can be NULL in which case the Parameter will not be placed within any ParameterGroup.
typeThe ParameterType for this Parameter.
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.
default_valueThe default value for this Parameter.
levelThe ParameterLevel for this Parameter. This determines when the Client should display this Parameter to the user.
Returns
A newly-allocated Parameter or NULL upon error.
See also
CreateAndAddParameterToParameterSet
Examples
long_running_service.c.

◆ GetParameterSetAsJSON()

json_t * GetParameterSetAsJSON ( const ParameterSet *const  param_set_p,
const SchemaVersion *const  sv_p,
const bool  full_definition_flag 
)

Generate a json-based description of a ParameterSet.

This uses the Swagger definitions as much as possible.

Parameters
param_set_pThe ParameterSet to generate the description for.
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 each of the Parameters will get added. If this is false then just the name and current value of each Parameter will get added. This is useful is you just want to send the values to use when running a service.
Returns
The json-based representation of the ParameterSet or NULL if there was an error.

◆ GetParameterSetSelectionAsJSON()

json_t * GetParameterSetSelectionAsJSON ( const ParameterSet *const  param_set_p,
const SchemaVersion *const  sv_p,
const bool  full_definition_flag,
void *  data_p,
bool(*)(const Parameter *param_p, void *data_p)  add_param_fn 
)

Generate a json-based description of a selection of ParameterSet.

Parameters
param_set_pThe ParameterSet to generate the description for.
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 each of the Parameters will get added. If this is false then just the name and current value of each Parameter will get added. This is useful is you just want to send the values to use when running a service.
data_pIf some custom data is needed by add_param_fn, then this can be used. It will be passed to each call of add_param_fn.
add_param_fnA callback function that determines whether a Parameter should be added to the generated JSON. This will be called for each Parameter in the ParameterSet along with data_p and if returns true then the Parameter's JSON will get added. If it returns false, then the Parameter will be skipped.
Returns
The json-based representation of the ParameterSet or NULL if there was an error.

◆ CreateParameterSetFromJSON()

ParameterSet * CreateParameterSetFromJSON ( const json_t *const  json_p,
struct Service service_p,
const bool  concise_flag 
)

Create a new ParameterSet from a json-based description.

This uses the Swagger definitions as much as possible.

Parameters
json_pThe json-based representation of the ParameterSet.
concise_flagIf this is true, then any Parameters within this ParameterSet will just have the 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
The newly-generated ParameterSet or NULL if there was an error.
See also
CreateParameterFromJSON

◆ GetParameterFromParameterSetByName()

Parameter * GetParameterFromParameterSetByName ( const ParameterSet *const  params_p,
const char *const  name_s 
)

Get the Parameter with a given name from a ParameterSet.

Parameters
params_pThe ParameterSet to search.
name_sThe Parameter name to try and match.
Returns
The Parameter with the matching name or NULL if it could not be found

◆ GetParameterNodeFromParameterSetByName()

ParameterNode * GetParameterNodeFromParameterSetByName ( const ParameterSet *const  params_p,
const char *const  name_s 
)

Get the ParameterNode for a Parameter with a given name from a ParameterSet.

Parameters
params_pThe ParameterSet to search.
name_sThe Parameter name to try and match.
Returns
The ParameterNode with the matching Parameter name or NULL if it could not be found

◆ GetParameterValueFromParameterSet()

bool GetParameterValueFromParameterSet ( const ParameterSet *const  params_p,
const char *const  name_s,
SharedType value_p,
const bool  current_value_flag 
)

Get the value of a Parameter within a ParameterSet.

Parameters
params_pThe ParameterSet to get the Parameter from.
name_sThe Parameter name to try and match.
value_pWhere the Parameter value will be stored upon success.
current_value_flagIf this is true then the current value of the Parameter will be retrieved. If this is false then the default value of the Parameter will be retrieved instead.
Returns
true if the Parameter value was retrieved successfully, false otherwise.
Examples
long_running_service.c.

◆ DetachParameterByName()

Parameter * DetachParameterByName ( ParameterSet params_p,
const char *const  name_s 
)

Remove the Parameter with a given name from a ParameterSet.

Parameters
params_pThe ParameterSet to search.
name_sThe name of the Parameter to try and match.
Returns
If found, the Parameter with the matching name will be removed from the ParameterSet and returned. If it could not be found NULL will be returned. be found.

◆ DetachParameter()

bool DetachParameter ( ParameterSet params_p,
Parameter param_p 
)

Remove the Parameter with from a ParameterSet.

Parameters
params_pThe ParameterSet to search.
param_pThe Parameter to try and deatch.
Returns
true if the Parameter was found and removed from the ParameterSet, false otherwise.

◆ GetParameterGroupFromParameterSetByGroupName()

struct ParameterGroup * GetParameterGroupFromParameterSetByGroupName ( const ParameterSet *const  params_p,
const char *const  name_s 
)

Get all of the Parameters within a given ParameterGroup.

Parameters
params_pThe ParameterSet to search.
name_sThe name of the ParameterGroup to get the Parameters for.
Returns
Upon success, an array of matching Parameter pointers terminated by a NULL. Upon failure a NULL is returned.

◆ AddParameterGroupToParameterSet()

bool AddParameterGroupToParameterSet ( ParameterSet param_set_p,
ParameterGroup group_p 
)

Add a ParameterGroup to a ParameterSet.

Parameters
param_set_pThe ParameterSet to add the ParameterGroup to.
group_pThe ParameterGroup to add.
Returns
true if the ParameterGroup was added successfully, false otherwise.

Field Documentation

◆ ps_name_s

const char* ps_name_s

An optional name for the ParameterSet.

This can be NULL.

◆ ps_description_s

const char* ps_description_s

An optional description for the ParameterSet.

This can be NULL.

◆ ps_params_p

LinkedList* ps_params_p

A LinkedList of ParameterNodes containing the Parameters.

◆ ps_grouped_params_p

LinkedList* ps_grouped_params_p

A LinkedList of ParameterGroupNodes for this ParameterSet.


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