parameter.h
Go to the documentation of this file.
1 /*
2 ** Copyright 2014-2016 The Earlham Institute
3 **
4 ** Licensed under the Apache License, Version 2.0 (the "License");
5 ** you may not use this file except in compliance with the License.
6 ** You may obtain a copy of the License at
7 **
8 ** http://www.apache.org/licenses/LICENSE-2.0
9 **
10 ** Unless required by applicable law or agreed to in writing, software
11 ** distributed under the License is distributed on an "AS IS" BASIS,
12 ** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 ** See the License for the specific language governing permissions and
14 ** limitations under the License.
15 */
16 
24 #ifndef PARAMETER_H
25 #define PARAMETER_H
26 
27 #include "uuid/uuid.h"
28 
29 #include "linked_list.h"
31 #include "data_resource.h"
32 #include "hash_table.h"
33 #include "schema_version.h"
34 #include "parameter_type.h"
36 #include "jansson.h"
37 
38 
39 /******* FORWARD DECLARATION *******/
40 struct Parameter;
41 struct ServiceData;
42 struct Service;
43 
52 typedef enum
53 {
59 
65 
72 
73 
85 typedef struct NamedParameterType
86 {
88  const char * const npt_name_s;
89 
96 
97 
104 #define SET_NAMED_PARAMETER_TYPE_TAGS(a,b) ({ .npt_name_s = a, .npt_type = b})
105 
106 /* forward declaration */
107 typedef struct Parameter Parameter;
108 
109 
110 
121 struct Parameter
122 {
125 
127  char *pa_name_s;
128 
131 
134 
135 
144 
149 
155 
162 
163 
170 
171 
177 
178 
187 
188 
193 
194 
195  void (*pa_clear_fn) (struct Parameter *param_p);
196 
197 
198  bool (*pa_add_values_to_json_fn) (const struct Parameter *param_p, json_t *param_json_p, const bool full_definition_flag);
199 
200  struct Parameter *(*pa_clone_fn) (const struct Parameter *param_p, const struct ServiceData *data_p);
201 
202  bool (*pa_set_value_from_string_fn) (struct Parameter *param_p, const char *value_s);
203 
204 
209 };
210 
211 
219 typedef struct ParameterNode
220 {
223 
226 } ParameterNode;
227 
228 
229 
230 
231 
232 #ifndef DOXYGEN_SHOULD_SKIP_THIS
233 
234 #ifdef ALLOCATE_PARAMETER_TAGS
235  #define PARAMETER_PREFIX GRASSROOTS_PARAMS_API
236  #define PARAMETER_VAL(x) = x
237 #else
238  #define PARAMETER_PREFIX extern
239  #define PARAMETER_VAL(x)
240 #endif
241 
242 #endif /* #ifndef DOXYGEN_SHOULD_SKIP_THIS */
243 
244 
245 PARAMETER_PREFIX const char * const PA_TABLE_COLUMN_HEADERS_PLACEMENT_S PARAMETER_VAL("Column Headers Placement");
246 
247 PARAMETER_PREFIX const char * const PA_TABLE_COLUMN_HEADINGS_S PARAMETER_VAL("Column Headings");
248 
249 PARAMETER_PREFIX const char * const PA_TABLE_ROW_HEADINGS_S PARAMETER_VAL("Row Headings");
250 
251 PARAMETER_PREFIX const char * const PA_TABLE_COLUMN_DELIMITER_S PARAMETER_VAL("Column Delimiter");
252 
253 PARAMETER_PREFIX const char * const PA_TABLE_ADD_COLUMNS_FLAG_S PARAMETER_VAL("Add User-Definable Columns");
254 
255 PARAMETER_PREFIX const char * const PA_TABLE_ROW_DELIMITER_S PARAMETER_VAL("Row Delimiter");
256 
257 PARAMETER_PREFIX const char * const PA_TABLE_DEFAULT_COLUMN_DELIMITER_S PARAMETER_VAL(",");
258 
259 PARAMETER_PREFIX const char * const PA_TABLE_DEFAULT_ROW_DELIMITER_S PARAMETER_VAL("\n");
260 
261 PARAMETER_PREFIX const char * const PA_DOUBLE_PRECISION_S PARAMETER_VAL("precision");
262 
263 
264 PARAMETER_PREFIX const char * const PA_TYPE_STRING_S PARAMETER_VAL("string");
265 
266 PARAMETER_PREFIX const char * const PA_TYPE_BOOLEAN_S PARAMETER_VAL("boolean");
267 
268 PARAMETER_PREFIX const char * const PA_TYPE_INTEGER_S PARAMETER_VAL("integer");
269 
270 PARAMETER_PREFIX const char * const PA_TYPE_NUMBER_S PARAMETER_VAL("number");
271 
272 PARAMETER_PREFIX const char * const PA_TYPE_CHARACTER_S PARAMETER_VAL("character");
273 
274 
275 PARAMETER_PREFIX const char * const PA_TABLE_COLUMN_HEADERS_PLACEMENT_FIRST_ROW_S PARAMETER_VAL("Column Headers Placement On First Row");
276 
277 
278 #ifdef __cplusplus
279  extern "C" {
280 #endif
281 
282 
283 
304 //GRASSROOTS_PARAMS_API Parameter *AllocateParameter (const struct ServiceData *service_data_p, ParameterType type, 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));
305 
306 
307 
308 GRASSROOTS_PARAMS_API bool InitParameter (Parameter *param_p, const struct ServiceData *service_data_p, ParameterType type, const char * const name_s,
309  const char * const display_name_s, const char * const description_s, ParameterLevel level,
310  void (*clear_fn) (Parameter *param_p),
311  bool (*add_values_to_json_fn) (const Parameter *param_p, json_t *param_json_p, const bool full_definition_flag),
312  struct Parameter *(*clone_fn) (const Parameter *param_p, const struct ServiceData *service_data_p),
313  bool (*set_value_from_string_fn) (struct Parameter *param_p, const char *value_s)
314 );
315 
316 
317 GRASSROOTS_PARAMS_API bool InitParameterFromJSON (Parameter *param_p, const json_t * const root_p, const struct Service *service_p, const bool concise_flag);
318 
319 
320 GRASSROOTS_PARAMS_API bool AddParameterValuesToJSON (const Parameter *param_p, json_t *param_json_p, const bool full_definition_flag);
321 
322 
330 GRASSROOTS_PARAMS_API Parameter *CloneParameter (const Parameter * const src_p, const struct ServiceData *data_p);
331 
332 
339 GRASSROOTS_PARAMS_API void FreeParameter (Parameter *param_p);
340 
341 
348 GRASSROOTS_PARAMS_API void ClearParameter (Parameter *param_p);
349 
350 
351 
352 
360 GRASSROOTS_PARAMS_API bool CompareParameterLevels (const ParameterLevel param_level, const ParameterLevel threshold);
361 
362 
363 
373 GRASSROOTS_PARAMS_API const char *CheckForSignedReal (const Parameter * const parameter_p, const void *value_p);
374 
375 
385 GRASSROOTS_PARAMS_API const char *CheckForNotNull (const Parameter * const parameter_p, const void *value_p);
386 
387 
400 GRASSROOTS_PARAMS_API bool AddParameterKeyStringValuePair (Parameter * const parameter_p, const char *key_s, const char *value_s);
401 
402 
403 GRASSROOTS_PARAMS_API bool AddParameterKeyJSONValuePair (Parameter * const parameter_p, const char *key_s, const json_t *value_p);
404 
405 
406 GRASSROOTS_PARAMS_API bool AddColumnParameterHint (const char *name_s, const char *description_s, const ParameterType param_type, const bool required_flag, json_t *array_p);
407 
408 
416 GRASSROOTS_PARAMS_API void RemoveParameterKeyValuePair (Parameter * const parameter_p, const char *key_s);
417 
418 
427 GRASSROOTS_PARAMS_API const char *GetParameterKeyValue (const Parameter * const parameter_p, const char *key_s);
428 
429 
446 GRASSROOTS_PARAMS_API json_t *GetParameterAsJSON (const Parameter * const parameter_p, const SchemaVersion * const sv_p, const bool full_definition_flag);
447 
448 
461 GRASSROOTS_PARAMS_API Parameter *CreateParameterFromJSON (const json_t * const root_p, struct Service *service_p, const bool concise_flag);
462 
463 
464 
475 GRASSROOTS_PARAMS_API bool IsJSONParameterConcise (const json_t * const json_p);
476 
477 
478 
487 GRASSROOTS_PARAMS_API const char *GetUIName (const Parameter * const parameter_p);
488 
489 
504 GRASSROOTS_PARAMS_API char *GetParameterValueAsString (const Parameter * const param_p, bool *alloc_flag_p);
505 
506 
516 GRASSROOTS_PARAMS_API bool SetParameterValueFromString (Parameter * const param_p, const char *value_s);
517 
518 
530 GRASSROOTS_PARAMS_API bool AddRemoteDetailsToParameter (Parameter *param_p, const char * const uri_s, const char * const name_s);
531 
532 
541 GRASSROOTS_PARAMS_API bool CopyRemoteParameterDetails (const Parameter * const src_param_p, Parameter *dest_param_p);
542 
543 
550 GRASSROOTS_PARAMS_API const char *GetGrassrootsTypeAsString (const ParameterType param_type);
551 
552 
560 GRASSROOTS_PARAMS_API bool GetGrassrootsTypeFromString (const char *param_type_s, ParameterType *param_type_p);
561 
562 
573 GRASSROOTS_PARAMS_API bool GetParameterGroupVisibility (const struct ServiceData *service_data_p, const char *group_name_s, bool *visibility_p);
574 
575 
586 GRASSROOTS_PARAMS_API bool GetParameterDescriptionFromConfig (const struct ServiceData *service_data_p, const char *param_name_s, char **description_ss);
587 
588 
599 GRASSROOTS_PARAMS_API bool GetParameterDisplayNameFromConfig (const struct ServiceData *service_data_p, const char *param_name_s, char **display_name_ss);
600 
601 
612 GRASSROOTS_PARAMS_API bool GetParameterLevelFromConfig (const struct ServiceData *service_data_p, const char *param_name_s, ParameterLevel *level_p);
613 
614 
623 GRASSROOTS_PARAMS_API const char *GetParameterLevelAsString (const ParameterLevel level);
624 
625 
626 
635 GRASSROOTS_PARAMS_API bool GetParameterLevelFromString (const char *level_s, ParameterLevel *level_p);
636 
637 
646 GRASSROOTS_PARAMS_API ParameterNode *AllocateParameterNode (Parameter *param_p);
647 
648 
655 GRASSROOTS_PARAMS_API void FreeParameterNode (ListItem *node_p);
656 
657 
678 GRASSROOTS_PARAMS_API json_t *GetRunnableParameterAsJSON (const Parameter *param_p, const SchemaVersion * const sv_p, const bool full_definition_flag);
679 
680 
681 GRASSROOTS_PARAMS_API bool AddParameterLevelToJSON (const ParameterLevel level, json_t *root_p, const SchemaVersion * const UNUSED_PARAM (sv_p));
682 
683 
684 
685 GRASSROOTS_PARAMS_API void SetParameterCallbacks (Parameter *param_p, void (*clear_fn) (Parameter *param_p),
686  bool (*add_values_to_json_fn) (const Parameter *param_p, json_t *param_json_p, const bool full_definition_flag),
687  Parameter *(*clone_fn) (const Parameter *param_p, const struct ServiceData *data_p),
688  bool (*set_value_from_string_fn) (Parameter *param_p, const char *value_s));
689 
690 
691 GRASSROOTS_PARAMS_API const json_t *GetParameterFromConfig (const json_t *service_config_p, const char * const param_name_s);
692 
693 
694 
695 GRASSROOTS_PARAMS_LOCAL bool AddNullParameterValueToJSON (json_t *param_json_p, const char *key_s);
696 
697 
698 #ifdef __cplusplus
699 }
700 #endif
701 
702 #endif /* #ifndef PARAMETER_H */
703 
A doubly-linked node that points to its predecessor and successor.
Definition: linked_list.h:43
ParameterType
The different types that a Parameter can take.
Definition: parameter_type.h:35
ParameterType pa_type
The type of the parameter.
Definition: parameter.h:124
Parameter * CloneParameter(const Parameter *const src_p, const struct ServiceData *data_p)
Clone a Parameter.
This is a datatype that stores a read-only c-style string along with a ParameterType.
Definition: parameter.h:85
ListItem pn_node
The ListItem.
Definition: parameter.h:222
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.
parameter_type.h
bool GetParameterGroupVisibility(const struct ServiceData *service_data_p, const char *group_name_s, bool *visibility_p)
Get the configured visibility value for a given ParameterGroup.
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.
LinkedList * pa_remote_parameter_details_p
A LinkedList of RemoteParameterNodes that hold the information for Parameters for PairedServices to t...
Definition: parameter.h:169
The value of a ParameterLevel for Parameters that are considered the most simple options.
Definition: parameter.h:58
bool pa_read_only_flag
Is the Parameter read-only?
Definition: parameter.h:208
const char * GetParameterLevelAsString(const ParameterLevel level)
Get the string representation of a given ParameterLevel.
const char * GetGrassrootsTypeAsString(const ParameterType param_type)
Get the human-readable name for a given ParameterType.
The value of a ParameterLevel for Parameters that are considered the options that require the most ex...
Definition: parameter.h:64
ParameterNode * AllocateParameterNode(Parameter *param_p)
Allocate a ParameterNode for a given Parameter so that it can be stored upon a LinkedList.
char * pa_display_name_s
An optional user-friendly name of the parameter to use for client user interfaces.
Definition: parameter.h:130
A container using HashBuckets to allow for fast lookup of key-value pairs.
Definition: hash_table.h:139
This is a datatype to store the versioning details for the Grassroots JSON schema that is being used.
Definition: schema_version.h:44
LinkedList * pa_options_p
If the parameter can only take one of a constrained set of values, this will be a LinkedList of Param...
Definition: parameter.h:143
Parameter * CreateParameterFromJSON(const json_t *const root_p, struct Service *service_p, const bool concise_flag)
Create a Parameter from a json-based representation.
char * GetParameterValueAsString(const Parameter *const param_p, bool *alloc_flag_p)
Get the current value of a Parameter as a string.
struct ParameterGroup * pa_group_p
The ParameterGroup to which this Parameter belongs.
Definition: parameter.h:161
A doubly-linked list.
bool GetParameterDescriptionFromConfig(const struct ServiceData *service_data_p, const char *param_name_s, char **description_ss)
Get the configured description for a given Parameter.
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.
A datatype for holding the configuration data for a Service.
Definition: service.h:126
A datatype to tell the system that certain parameters should be grouped together in the client's user...
Definition: parameter_group.h:85
A datatype which defines an available service, its capabilities and its parameters.
Definition: service.h:153
A doubly-linked list that can be traversed in either direction.
Definition: linked_list.h:56
const char * GetUIName(const Parameter *const parameter_p)
Get the name to use for a Client to use for this Parameter.
bool GetParameterLevelFromConfig(const struct ServiceData *service_data_p, const char *param_name_s, ParameterLevel *level_p)
Get the configured ParameterLevel for a given Parameter.
ParameterLevel
The ParameterLevel defines the level that a user should be to adjust the Parameter.
Definition: parameter.h:52
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.
bool CompareParameterLevels(const ParameterLevel param_level, const ParameterLevel threshold)
Test whether a given ParameterLevel matches or exceeds another.
bool pa_required_flag
Must this Parameter contain a valid value or can it be empty?
Definition: parameter.h:192
bool AddParameterKeyStringValuePair(Parameter *const parameter_p, const char *key_s, const char *value_s)
Add a key value pair to a Parameter.
const char * CheckForNotNull(const Parameter *const parameter_p, const void *value_p)
Check whether the value of a Parameter is not NULL.
ParameterLevel pa_level
The level of the parameter.
Definition: parameter.h:148
The datatype that stores all of the information about a Parameter.
Definition: parameter.h:121
HashTable * pa_store_p
A map allowing the Parameter to store an arbitrary set of key-value pairs.
Definition: parameter.h:154
char * pa_description_s
The description for this parameter.
Definition: parameter.h:133
const ParameterType npt_type
The read-only ParameterType for the Parameter with the name given by npt_name_s.
Definition: parameter.h:94
void ClearParameter(Parameter *param_p)
Clear a Parameter.
void FreeParameter(Parameter *param_p)
Free a Parameter.
const char * GetParameterKeyValue(const Parameter *const parameter_p, const char *key_s)
Get a value from a Parameter.
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.
bool GetGrassrootsTypeFromString(const char *param_type_s, ParameterType *param_type_p)
Get the ParameterType from its human-readable name.
bool AddNullParameterValueToJSON(json_t *param_json_p, const char *key_s)
@prviate
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.
The value of a ParameterLevel for Parameters that are considered the options suitable for all levels.
Definition: parameter.h:70
A datatype for storing Parameters in a LinkedList.
Definition: parameter.h:219
bool GetParameterLevelFromString(const char *level_s, ParameterLevel *level_p)
Get the ParameterLevel from a string representation.
void FreeParameterNode(ListItem *node_p)
Free a ParameterNode.
void RemoveParameterKeyValuePair(Parameter *const parameter_p, const char *key_s)
Remove a key value pair from a Parameter.
Parameter * pn_parameter_p
Pointer to the associated Parameter.
Definition: parameter.h:225
bool pa_visible_flag
Should this Parameter be displayed to the user or is it a hidden variable.
Definition: parameter.h:176
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 ...
Definition: parameter.h:186
char * pa_name_s
The name of the parameter.
Definition: parameter.h:127
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.
const char *const npt_name_s
The read-only name of the Parameter.
Definition: parameter.h:88
bool SetParameterValueFromString(Parameter *const param_p, const char *value_s)
Set the current value of a Parameter from a string.
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 curren...