string_parameter.h

Go to the documentation of this file.

/*
** Copyright 2014-2020 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.
*/
/*
 * char_parameter.h
 *
 *  Created on: 30 Jan 2020
 *      Author: billy
 */
 
#ifndef CORE_SHARED_PARAMETERS_INCLUDE_STRING_PARAMETER_H_
#define CORE_SHARED_PARAMETERS_INCLUDE_STRING_PARAMETER_H_
 
 
#include "parameter.h"
#include "parameter_set.h"
#include "grassroots_service_library.h"
 
 
typedef struct StringParameter
{
  Parameter sp_base_param;
 
  char *sp_current_value_s;
 
  char *sp_default_value_s;
 
  char *sp_min_value_s;
 
  char *sp_max_value_s;
 
} StringParameter;
 
 
 
typedef struct StringParameterOption
{
  char *spo_value_s;
 
  char *spo_description_s;
 
} StringParameterOption;
 
 
typedef struct StringParameterOptionNode
{
  ListItem spon_node;
 
  StringParameterOption *spon_option_p;
 
} StringParameterOptionNode;
 
 
#ifdef __cplusplus
extern "C"
{
#endif
 
/*
 * Allocate a StringParameter
 *
 * @param service_data_p The ServiceData for the Service that is allocating this Parameter.
 * @param name_s The name of the Parameter. The Parameter will store a copy of this string so this value does not need to remain in scope.
 * @param display_name_s An 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 <code>NULL</code>.
 * @param description_s The description of the Parameter. The Parameter will store a copy of this string so this value does not need to remain in scope.
 * @param options_p This can be used to constrain the Parameter to a fixed set of values. If this is <code>NULL</code> then the Parameter can be set to any value.
 * @param default_value_p The default value for this Parameter.
 * @param current_value_p If this is not <code>NULL</code>, then copy this value as the current value of the Parameter. If this is <code>NULL</code>, then current value for this Parameter
 * will be set to be a copy of its default value.
 * @param bounds_p If this is not <code>NULL</code>, then this will be used to specify the minimum and maximum values that this Parameter can take. If this is <code>NULL</code>,
 * then the Parameter can take any value.
 * @param level The ParameterLevel for this Parameter. This determines when the Client should display this Parameter to the user.
 * @param check_value_fn If this is not <code>NULL</code>, then this will be used to check whether the Parameter has been set to a valid value.
 * @return A newly-allocated Parameter or <code>NULL</code> upon error.
 * @memberof BooleanParameter
 */
GRASSROOTS_SERVICE_API StringParameter *AllocateStringParameter (const struct ServiceData *service_data_p, const ParameterType pt, const char * const name_s, const char * const display_name_s, const char * const description_s, const char *default_value_p, const char *current_value_p, ParameterLevel level);
 
 
GRASSROOTS_SERVICE_API StringParameter *AllocateStringParameterFromJSON (const json_t *param_json_p, const struct Service *service_p, const bool concise_flag, const ParameterType *pt_p);
 
 
GRASSROOTS_SERVICE_API Parameter *EasyCreateAndAddStringParameterToParameterSet (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,
                                                      const char *default_value_s, uint8 level);
 
 
GRASSROOTS_SERVICE_API Parameter *CreateAndAddStringParameterToParameterSet (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,
                                                      const char *default_value_s, const char *current_value_s, uint8 level);
 
 
 
GRASSROOTS_SERVICE_API void FreeStringParameter (StringParameter *param_p);
 
 
GRASSROOTS_SERVICE_API const char *GetStringParameterCurrentValue (const StringParameter *param_p);
 
 
GRASSROOTS_SERVICE_API bool SetStringParameterCurrentValue (StringParameter *param_p, const char *value_p);
 
 
GRASSROOTS_SERVICE_API const char *GetStringParameterDefaultValue (const StringParameter *param_p);
 
 
GRASSROOTS_SERVICE_API bool SetStringParameterDefaultValue (StringParameter *param_p, const char *value_p);
 
 
GRASSROOTS_SERVICE_API bool SetStringParameterBounds (StringParameter *param_p, const char *min_value_s, const char *max_value_s);
 
 
GRASSROOTS_SERVICE_API bool IsStringParameterBounded (const StringParameter *param_p);
 
 
GRASSROOTS_SERVICE_API bool GetStringParameterBounds (const StringParameter *param_p, const char **min_pp, const char **max_pp);
 
 
GRASSROOTS_SERVICE_API bool CreateAndAddStringParameterOption (Parameter *param_p, const char *value_s, const char *description_s);
 
 
GRASSROOTS_SERVICE_API StringParameterOption *AllocateStringParameterOption (const char *value_s, const char *description_s);
 
 
GRASSROOTS_SERVICE_API StringParameterOptionNode *AllocateStringParameterOptionNode (StringParameterOption *option_p);
 
 
GRASSROOTS_SERVICE_API void FreeStringParameterOption (StringParameterOption *option_p);
 
 
GRASSROOTS_SERVICE_API bool IsStringParameter (const Parameter *param_p);
 
 
GRASSROOTS_SERVICE_API bool GetCurrentStringParameterValueFromParameterSet (const ParameterSet * const params_p, const char * const name_s, const char **value_pp);
 
 
 
GRASSROOTS_SERVICE_API bool GetCurrentStringParameterValueFromParameterGroup (const ParameterGroup * const params_p, const char * const name_s, const char **value_pp);
 
 
GRASSROOTS_SERVICE_API bool SetStringParameterCurrentValueFromJSON (StringParameter *param_p, const json_t *value_p);
 
 
GRASSROOTS_SERVICE_API bool AddStringParameterOptionsToJSON (const Parameter *param_p, json_t *param_json_p);
 
 
GRASSROOTS_SERVICE_API bool GetStringParameterOptionsFromJSON (Parameter *param_p, const json_t * const json_p);
 
 
GRASSROOTS_SERVICE_API bool CopyStringParameterOptions (const Parameter *src_p, Parameter *dest_p, const bool clear_existing_dest_options_flag);
 
 
#ifdef __cplusplus
}
#endif
 
#endif /* CORE_SHARED_PARAMETERS_INCLUDE_STRING_PARAMETER_H_ */