parameter.h

Go to the documentation of this file.

/*
** Copyright 2014-2016 The Earlham Institute
**
** Licensed under the Apache License, Version 2.0 (the "License");
** you may not use this file except in compliance with the License.
** You may obtain a copy of the License at
**
**     http://www.apache.org/licenses/LICENSE-2.0
**
** Unless required by applicable law or agreed to in writing, software
** distributed under the License is distributed on an "AS IS" BASIS,
** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
** See the License for the specific language governing permissions and
** limitations under the License.
*/
 
#ifndef PARAMETER_H
#define PARAMETER_H
 
#include "uuid_defs.h"
 
#include "linked_list.h"
#include "grassroots_service_library.h"
#include "data_resource.h"
#include "hash_table.h"
#include "schema_version.h"
#include "parameter_type.h"
#include "remote_parameter_details.h"
#include "jansson.h"
 
 
/******* FORWARD DECLARATION *******/
struct Parameter;
struct ServiceData;
struct Service;
 
typedef enum
{
  PL_SIMPLE,
 
  PL_ADVANCED,
 
  PL_ALL
} ParameterLevel;
 
 
typedef struct NamedParameterType
{
  const char * const npt_name_s;
 
  const ParameterType npt_type;
} NamedParameterType;
 
 
#define SET_NAMED_PARAMETER_TYPE_TAGS(a,b) ({ .npt_name_s = a, .npt_type = b})
 
/* forward declaration */
typedef struct Parameter Parameter;
 
 
 
struct Parameter
{
  ParameterType pa_type;
 
  char *pa_name_s;
 
  char *pa_display_name_s;
 
  char *pa_description_s;
 
 
  LinkedList *pa_options_p;
 
  ParameterLevel pa_level;
 
  HashTable *pa_store_p;
 
  struct ParameterGroup *pa_group_p;
 
 
  LinkedList *pa_remote_parameter_details_p;
 
 
  bool pa_visible_flag;
 
 
  bool pa_refresh_service_flag;
 
 
  bool pa_required_flag;
 
 
  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;
};
 
 
typedef struct ParameterNode
{
  ListItem pn_node;
 
  Parameter *pn_parameter_p;
} ParameterNode;
 
 
 
#ifndef DOXYGEN_SHOULD_SKIP_THIS
 
 
#ifdef ALLOCATE_PARAMETER_TAGS
  #define PARAMETER_PREFIX  GRASSROOTS_SERVICE_API
  #define PARAMETER_VAL(x) = x
  #define PARAMETER_CONCAT_VAL(x,y) = x y
#else
  #define PARAMETER_PREFIX extern GRASSROOTS_SERVICE_API
  #define PARAMETER_VAL(x)
  #define PARAMETER_CONCAT_VAL(x,y)
#endif
 
#endif    /* #ifndef DOXYGEN_SHOULD_SKIP_THIS */
 
#ifdef __cplusplus
extern "C" {
#endif
 
 
 
 
PARAMETER_PREFIX const char * const PA_TABLE_COLUMN_HEADERS_PLACEMENT_S PARAMETER_VAL("Column Headers Placement");
 
PARAMETER_PREFIX const char * const PA_TABLE_COLUMN_HEADINGS_S PARAMETER_VAL("Column Headings");
 
PARAMETER_PREFIX const char * const PA_TABLE_ROW_HEADINGS_S PARAMETER_VAL("Row Headings");
 
PARAMETER_PREFIX const char * const PA_TABLE_COLUMN_DELIMITER_S PARAMETER_VAL("Column Delimiter");
 
PARAMETER_PREFIX const char * const PA_TABLE_ADD_COLUMNS_FLAG_S PARAMETER_VAL("Add User-Definable Columns");
 
PARAMETER_PREFIX const char * const PA_TABLE_ROW_DELIMITER_S PARAMETER_VAL("Row Delimiter");
 
PARAMETER_PREFIX const char * const PA_TABLE_DEFAULT_COLUMN_DELIMITER_S PARAMETER_VAL(",");
 
PARAMETER_PREFIX const char * const PA_TABLE_DEFAULT_ROW_DELIMITER_S PARAMETER_VAL("\n");
 
PARAMETER_PREFIX const char * const PA_DOUBLE_PRECISION_S PARAMETER_VAL("precision");
 
PARAMETER_PREFIX const char * const PA_TYPE_STRING_ARRAY_S PARAMETER_VAL("string_array");
 
PARAMETER_PREFIX const char * const PA_TYPE_TIME_ARRAY_S PARAMETER_VAL("time_array");
 
PARAMETER_PREFIX const char * const PA_TYPE_STRING_S PARAMETER_VAL("string");
 
PARAMETER_PREFIX const char * const PA_TYPE_BOOLEAN_S PARAMETER_VAL("boolean");
 
PARAMETER_PREFIX const char * const PA_TYPE_INTEGER_S PARAMETER_VAL("integer");
 
PARAMETER_PREFIX const char * const PA_TYPE_NUMBER_S PARAMETER_VAL("number");
 
PARAMETER_PREFIX const char * const PA_TYPE_CHARACTER_S PARAMETER_VAL("character");
 
 
PARAMETER_PREFIX const char * const PA_TABLE_COLUMN_HEADERS_PLACEMENT_FIRST_ROW_S PARAMETER_VAL("Column Headers Placement On First Row");
 
 
 
 
//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));
 
 
 
GRASSROOTS_SERVICE_API 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)
);
 
 
 
GRASSROOTS_SERVICE_API void NullifyParameter (Parameter *param_p);
 
 
GRASSROOTS_SERVICE_API bool InitParameterFromJSON (Parameter *param_p, const json_t * const root_p, const struct Service *service_p, const bool concise_flag, const ParameterType *pt_p);
 
 
GRASSROOTS_SERVICE_API bool AddParameterValuesToJSON (const Parameter *param_p, json_t *param_json_p, const bool full_definition_flag);
 
 
GRASSROOTS_SERVICE_API Parameter *CloneParameter (const Parameter * const src_p, const struct ServiceData *data_p);
 
 
GRASSROOTS_SERVICE_API void FreeParameter (Parameter *param_p);
 
 
GRASSROOTS_SERVICE_API void ClearParameter (Parameter *param_p);
 
 
 
 
GRASSROOTS_SERVICE_API bool CompareParameterLevels (const ParameterLevel param_level, const ParameterLevel threshold);
 
 
 
GRASSROOTS_SERVICE_API const char *CheckForSignedReal (const Parameter * const parameter_p, const void *value_p);
 
 
GRASSROOTS_SERVICE_API const char *CheckForNotNull (const Parameter * const parameter_p, const void *value_p);
 
 
GRASSROOTS_SERVICE_API bool AddParameterKeyStringValuePair (Parameter * const parameter_p, const char *key_s, const char *value_s);
 
 
GRASSROOTS_SERVICE_API bool AddParameterKeyJSONValuePair (Parameter * const parameter_p, const char *key_s, const json_t *value_p);
 
 
GRASSROOTS_SERVICE_API bool AddColumnParameterHint (const char *name_s, const char *description_s, const ParameterType param_type, const bool required_flag, json_t *array_p);
 
 
GRASSROOTS_SERVICE_API void RemoveParameterKeyValuePair (Parameter * const parameter_p, const char *key_s);
 
 
GRASSROOTS_SERVICE_API const char *GetParameterKeyValue (const Parameter * const parameter_p, const char *key_s);
 
 
GRASSROOTS_SERVICE_API json_t *GetParameterAsJSON (const Parameter * const parameter_p, const SchemaVersion * const sv_p, const bool full_definition_flag);
 
 
GRASSROOTS_SERVICE_API Parameter *CreateParameterFromJSON (const json_t * const root_p, struct Service *service_p, const bool concise_flag);
 
 
 
GRASSROOTS_SERVICE_API bool IsJSONParameterConcise (const json_t * const json_p);
 
 
 
GRASSROOTS_SERVICE_API const char *GetUIName (const Parameter * const parameter_p);
 
 
GRASSROOTS_SERVICE_API char *GetParameterValueAsString (const Parameter * const param_p, bool *alloc_flag_p);
 
 
GRASSROOTS_SERVICE_API bool SetParameterCurrentValueFromString (Parameter * const param_p, const char *value_s);
 
 
GRASSROOTS_SERVICE_API bool AddRemoteDetailsToParameter (Parameter *param_p, const char * const uri_s, const char * const name_s);
 
 
GRASSROOTS_SERVICE_API bool CopyRemoteParameterDetails (const Parameter * const src_param_p, Parameter *dest_param_p);
 
 
GRASSROOTS_SERVICE_API const char *GetGrassrootsTypeAsString (const ParameterType param_type);
 
 
GRASSROOTS_SERVICE_API bool GetGrassrootsTypeFromString (const char *param_type_s, ParameterType *param_type_p);
 
 
GRASSROOTS_SERVICE_API bool GetParameterGroupVisibility (const struct ServiceData *service_data_p, const char *group_name_s, bool *visibility_p);
 
 
GRASSROOTS_SERVICE_API bool GetParameterDescriptionFromConfig (const struct ServiceData *service_data_p, const char *param_name_s, char **description_ss);
 
 
GRASSROOTS_SERVICE_API bool GetParameterDisplayNameFromConfig (const struct ServiceData *service_data_p, const char *param_name_s, char **display_name_ss);
 
 
GRASSROOTS_SERVICE_API bool GetParameterLevelFromConfig (const struct ServiceData *service_data_p, const char *param_name_s, ParameterLevel *level_p);
 
 
GRASSROOTS_SERVICE_API const char *GetParameterLevelAsString (const ParameterLevel level);
 
 
 
GRASSROOTS_SERVICE_API bool GetParameterLevelFromString (const char *level_s, ParameterLevel *level_p);
 
 
GRASSROOTS_SERVICE_API ParameterNode *AllocateParameterNode (Parameter *param_p);
 
 
GRASSROOTS_SERVICE_API void FreeParameterNode (ListItem *node_p);
 
 
GRASSROOTS_SERVICE_API json_t *GetRunnableParameterAsJSON (const Parameter *param_p, const SchemaVersion * const sv_p, const bool full_definition_flag);
 
 
GRASSROOTS_SERVICE_API bool AddParameterLevelToJSON (const ParameterLevel level, json_t *root_p, const SchemaVersion * const UNUSED_PARAM (sv_p));
 
 
 
GRASSROOTS_SERVICE_API void SetParameterCallbacks (Parameter *param_p, 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),
                            Parameter *(*clone_fn) (const Parameter *param_p, const struct ServiceData *data_p),
                            bool (*set_value_from_string_fn) (Parameter *param_p, const char *value_s));
 
 
GRASSROOTS_SERVICE_API const json_t *GetParameterFromConfig (const json_t *service_config_p, const char * const param_name_s);
 
 
 
GRASSROOTS_SERVICE_LOCAL bool AddNullParameterValueToJSON (json_t *param_json_p, const char *key_s);
 
 
 
GRASSROOTS_SERVICE_API bool SetParameterCurrentValueFromJSON (Parameter *param_p, const json_t *value_p);
 
 
GRASSROOTS_SERVICE_API const char *GetNamedParameterDefaultValueFromJSON (const char *id_param_s, const json_t *params_json_p);
 
 
GRASSROOTS_SERVICE_API LinkedList *GetParameterStringMultiOptions (Parameter *param_p);
 
 
#ifdef __cplusplus
}
#endif
 
#endif  /* #ifndef PARAMETER_H */