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

#include <parameter.h>

Collaboration diagram for Parameter:
[legend]

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...
 
ParameterCloneParameter (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...
 
ParameterCreateParameterFromJSON (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 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 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...
 
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 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...
 
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...
 
ParameterLevel pa_level
 The level of the 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...
 
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.

Examples
long_running_service.c.

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_pThe ServiceData for the Service that is allocating this Parameter.
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.
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,
const struct ServiceData data_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.

◆ ClearParameter()

void ClearParameter ( Parameter param_p)

Clear a Parameter.

Parameters
param_pThe 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_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.

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

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

◆ GetParameterLevelAsString()

const char * GetParameterLevelAsString ( const ParameterLevel  level)

Get the string representation of a given ParameterLevel.

Parameters
levelThe 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_sThe string representation of the ParameterLevel
levelThe 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_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 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_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

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 ananlagous 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_read_only_flag

bool pa_read_only_flag

Is the Parameter read-only?


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