Loading...
Searching...
No Matches
Parameters

## Typedefs

typedef struct _cpl_parameter_ | cpl_parameter
| The opaque parameter data type.
typedef enum _cpl_parameter_class_ | cpl_parameter_class
| The parameter class data type.
typedef enum _cpl_parameter_mode_ | cpl_parameter_mode
| The parameter mode data type.

## Enumerations

enum | _cpl_parameter_class_ { CPL_PARAMETER_CLASS_INVALID , CPL_PARAMETER_CLASS_VALUE , CPL_PARAMETER_CLASS_RANGE , CPL_PARAMETER_CLASS_ENUM }
| Supported parameter classes. More...
enum | _cpl_parameter_mode_ { CPL_PARAMETER_MODE_CLI , CPL_PARAMETER_MODE_ENV , CPL_PARAMETER_MODE_CFG }
| Supported parameter modes. More...

## Functions

void | cpl_parameter_delete (cpl_parameter *self)
| Delete a parameter.
cpl_error_code | cpl_parameter_disable (cpl_parameter *self, cpl_parameter_mode mode)
| Deactivate a parameter for the given mode.
void | cpl_parameter_dump (const cpl_parameter *self, FILE *stream)
| Dump the parameter debugging information to the given stream.
cpl_parameter * | cpl_parameter_duplicate (const cpl_parameter *self)
| Create a copy of a parameter.
cpl_error_code | cpl_parameter_enable (cpl_parameter *self, cpl_parameter_mode mode)
| Activates a parameter for the given mode.
const char * | cpl_parameter_get_alias (const cpl_parameter *self, cpl_parameter_mode mode)
| Get the parameter's alias name for the given mode.
int | cpl_parameter_get_bool (const cpl_parameter *self)
| Get the value of the given boolean parameter.
cpl_parameter_class | cpl_parameter_get_class (const cpl_parameter *self)
| Get the parameter's class.
const char * | cpl_parameter_get_context (const cpl_parameter *self)
| Get the context of a parameter.
int | cpl_parameter_get_default_bool (const cpl_parameter *self)
| Get the default value of the given boolean parameter.
double | cpl_parameter_get_default_double (const cpl_parameter *self)
| Get the default value of the given double parameter.
int | cpl_parameter_get_default_flag (const cpl_parameter *self)
| Get the presence status flag of the given parameter.
int | cpl_parameter_get_default_int (const cpl_parameter *self)
| Get the default value of the given integer parameter.
const char * | cpl_parameter_get_default_string (const cpl_parameter *self)
| Get the default value of the given string parameter.
double | cpl_parameter_get_double (const cpl_parameter *self)
| Get the value of the given double parameter.
double | cpl_parameter_get_enum_double (const cpl_parameter *self, int position)
| Get the possible values for a double enumeration.
int | cpl_parameter_get_enum_int (const cpl_parameter *self, int position)
| Get the possible values for an integer enumeration.
int | cpl_parameter_get_enum_size (const cpl_parameter *self)
| Get the number of alternatives of an enumeration parameter.
const char * | cpl_parameter_get_enum_string (const cpl_parameter *self, int position)
| Get the possible values for a string enumeration.
const char * | cpl_parameter_get_help (const cpl_parameter *self)
| Get the description of a parameter.
int | cpl_parameter_get_id (const cpl_parameter *self)
| Change the presence status flag of the given parameter.
int | cpl_parameter_get_int (const cpl_parameter *self)
| Get the value of the given integer parameter.
const char * | cpl_parameter_get_name (const cpl_parameter *self)
| Get the name of a parameter.
double | cpl_parameter_get_range_max_double (const cpl_parameter *self)
| Get the maximum value of a double range parameter.
int | cpl_parameter_get_range_max_int (const cpl_parameter *self)
| Get the maximum value of an integer range parameter.
double | cpl_parameter_get_range_min_double (const cpl_parameter *self)
| Get the minimum value of a double range parameter.
int | cpl_parameter_get_range_min_int (const cpl_parameter *self)
| Get the minimum value of an integer range parameter.
const char * | cpl_parameter_get_string (const cpl_parameter *self)
| Get the value of the given string parameter.
const char * | cpl_parameter_get_tag (const cpl_parameter *self)
| Get the parameter's user tag.
cpl_type | cpl_parameter_get_type (const cpl_parameter *self)
| Get the parameter's value type.
int | cpl_parameter_is_enabled (const cpl_parameter *self, cpl_parameter_mode mode)
| Get the parameter's activity status for the environment context.
cpl_parameter * | cpl_parameter_new_enum (const char *name, cpl_type type, const char *description, const char *context,...)
| Create a new enumeration parameter.
cpl_parameter * | cpl_parameter_new_enum_from_array (const char *name, cpl_type type, const char *description, const char *context, cpl_size position, cpl_size size, const void *alternatives)
| Create a new enumeration parameter from an array of alternative values.
cpl_parameter * | cpl_parameter_new_range (const char *name, cpl_type type, const char *description, const char *context,...)
| Create a new range parameter.
cpl_parameter * | cpl_parameter_new_value (const char *name, cpl_type type, const char *description, const char *context,...)
| Create a new value parameter.
cpl_error_code | cpl_parameter_set_alias (cpl_parameter *self, cpl_parameter_mode mode, const char *alias)
| Set alias names for the given parameter.
cpl_error_code | cpl_parameter_set_bool (cpl_parameter *self, int value)
| Assign a boolean value to a parameter.
cpl_error_code | cpl_parameter_set_default_bool (cpl_parameter *self, int value)
| Modify the default value of a boolean parameter.
cpl_error_code | cpl_parameter_set_default_double (cpl_parameter *self, double value)
| Modify the default value of a double parameter.
cpl_error_code | cpl_parameter_set_default_int (cpl_parameter *self, int value)
| Modify the default value of an integer parameter.
cpl_error_code | cpl_parameter_set_default_string (cpl_parameter *self, const char *value)
| Modify the default value of a string parameter.
cpl_error_code | cpl_parameter_set_double (cpl_parameter *self, double value)
| Assign a double value to a parameter.
cpl_error_code | cpl_parameter_set_id (cpl_parameter *self, int id)
| Set the numerical identifier of the given parameter.
cpl_error_code | cpl_parameter_set_int (cpl_parameter *self, int value)
| Assign an integer value to a parameter.
cpl_error_code | cpl_parameter_set_string (cpl_parameter *self, const char *value)
| Assign a string value to a parameter.
cpl_error_code | cpl_parameter_set_tag (cpl_parameter *self, const char *tag)
| Set the tag of the given parameter.

## Detailed Description

This module implements a class of data types which can be used to manage context specific, named parameters. They provide a standard way to pass, for instance, command line information to different components of an application.

The fundamental parts of a parameter are its name, a context to which it belongs (a specific component of an application for instance), its current value and a default value.

The implementation supports three classes of parameters:

- A plain value
- A range of values
- An enumeration value

When a parameter is created it is created for a particular value type. The type of a parameter's current and default value may be (cf. Type codes):

- `CPL_TYPE_BOOL`
- `CPL_TYPE_INT`
- `CPL_TYPE_DOUBLE`
- `CPL_TYPE_STRING`

When a value is assigned to a parameter, the different parameter classes behave differently. For a plain value, no checks are applied to the data value to be assigned. For a range or an enumeration, on the other hand, the value to be stored is validated with respect to the minimum and maximum value of the range and the list of enumeration alternatives respectively. If the value is invalid, an error is reported.

Note
  The validation of parameter values on assignment is not yet implemented.

The functions to create a new parameter of a particular class are polymorphic and accept any value type mentioned above to initialise the parameter to create. This is accomplished by using a variable argument list. The number and type of the parameters expected by these functions is determined from the parameter class and the indicated value type.

The constructor of a plain value expects a single value, the parameter's default value, which must be of the appropriate type, as argument while the constructor of a range parameter expects the default value, followed by the minimum value and the maximum value. The constructor of an enumeration parameter expects as arguments the default value, the number of possible enumeration values followed by the list of the possible enumeration values. Note that the default value must be a member of the list of possible enumeration values.

An example of how parameters of the different classes are created and destroyed is shown below:

cpl_parameter *value;
cpl_parameter *range;
cpl_parameter *enumeration;
...
value = cpl_parameter_new_value("Value", CPL_TYPE_INT,
"This is a plain value of type integer",
"Example",
-1);
range = cpl_parameter_new_range("Range", CPL_TYPE_DOUBLE,
"This is a value range of type double",
"Example",
0.5, 0.0, 1.0);
enumeration = cpl_parameter_new_enum("Enum", CPL_TYPE_STRING,
"This is an enumeration of type "
"string",
"Example",
"first", 3, "first", "second",
"third");
...
cpl_parameter_delete(value);
cpl_parameter_delete(range);
cpl_parameter_delete(enumeration);
cpl_parameter_new_enum
cpl_parameter * cpl_parameter_new_enum(const char *name, cpl_type type, const char *description, const char *context,...)
Create a new enumeration parameter.
Definition cpl_parameter.c:1101
cpl_parameter
struct _cpl_parameter_ cpl_parameter
The opaque parameter data type.
Definition cpl_parameter.h:131
cpl_parameter_delete
void cpl_parameter_delete(cpl_parameter *self)
Delete a parameter.
Definition cpl_parameter.c:1403
cpl_parameter_new_value
cpl_parameter * cpl_parameter_new_value(const char *name, cpl_type type, const char *description, const char *context,...)
Create a new value parameter.
Definition cpl_parameter.c:858
cpl_parameter_new_range
cpl_parameter * cpl_parameter_new_range(const char *name, cpl_type type, const char *description, const char *context,...)
Create a new range parameter.
Definition cpl_parameter.c:971
CPL_TYPE_DOUBLE
@ CPL_TYPE_DOUBLE
Definition cpl_type.h:134
CPL_TYPE_STRING
@ CPL_TYPE_STRING
Definition cpl_type.h:164
CPL_TYPE_INT
@ CPL_TYPE_INT
Definition cpl_type.h:92

After the parameter has been created and initialised the parameters current value equals its default value. The initialisation values are copied into the parameter, i.e. if an initialiser value resides in dynamically allocated memory, it can be deallocated after the parameter has been initialised without affecting the created parameter.

Note
  A variable argument list allows only limited type checking. Therefore, code explicitly what you mean and double check the constructor calls that the number of arguments and the types of the elements of the variable argument list are what the constructor expects. For instance, if a constructor takes a floating-point argument do not forget to put the decimal point at the end!

Synopsis:
  #include <cpl_parameter.h>

## Typedef Documentation

## cpl_parameter

typedef struct _cpl_parameter_ cpl_parameter

The opaque parameter data type.

## cpl_parameter_class

typedef enum _cpl_parameter_class_ cpl_parameter_class

The parameter class data type.

## cpl_parameter_mode

typedef enum _cpl_parameter_mode_ cpl_parameter_mode

The parameter mode data type.

## Enumeration Type Documentation

## _cpl_parameter_class_

enum _cpl_parameter_class_

Supported parameter classes.

Enumerator
CPL_PARAMETER_CLASS_INVALID | Parameter of undefined or invalid class.
CPL_PARAMETER_CLASS_VALUE | Parameter representing a plain value.
CPL_PARAMETER_CLASS_RANGE | Parameter representing a range of values.
CPL_PARAMETER_CLASS_ENUM | Parameter representing an enumeration value.

## _cpl_parameter_mode_

enum _cpl_parameter_mode_

Supported parameter modes.

The parameter mode is used to set or get context specific parameter attributes.

Enumerator
CPL_PARAMETER_MODE_CLI | Command line mode of the parameter.
CPL_PARAMETER_MODE_ENV | Environment variable mode of the parameter.
CPL_PARAMETER_MODE_CFG | Configuration file mode of the parameter.

## Function Documentation

## cpl_parameter_delete()

void cpl_parameter_delete | ( | cpl_parameter * | self | ) |

Delete a parameter.

Parameters

  self | The parameter to delete.

Returns
  Nothing.

The function deletes a parameter of any class and type. All memory resources acquired by the parameter during its usage are released. If the parameter self is `NULL`, nothing is done and no error is set.

References CPL_PARAMETER_CLASS_ENUM, CPL_PARAMETER_CLASS_RANGE, and CPL_PARAMETER_CLASS_VALUE.

Referenced by cpl_parameter_duplicate(), cpl_parameter_new_enum(), cpl_parameter_new_range(), cpl_parameter_new_value(), and cpl_parameterlist_delete().

## cpl_parameter_disable()

cpl_error_code cpl_parameter_disable | ( | cpl_parameter * | self,
|  | cpl_parameter_mode | mode )

Deactivate a parameter for the given mode.

Parameters

  self | A parameter.
  mode | The parameter mode.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT | The parameter mode mode is not supported.

@enderror

The function disables the parameter self for the given mode mode.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, cpl_parameter_get_name(), CPL_PARAMETER_MODE_CFG, CPL_PARAMETER_MODE_CLI, and CPL_PARAMETER_MODE_ENV.

## cpl_parameter_dump()

void cpl_parameter_dump | ( | const cpl_parameter * | self,
|  | FILE * | stream )

Dump the parameter debugging information to the given stream.

Parameters

  self | The parameter.
  stream | The output stream to use.

Returns
  Nothing.

The function dumps the contents of of the parameter self to the output stream stream. If stream is `NULL` the function writes to the standard output. If self is `NULL` the function does nothing.

References CPL_PARAMETER_CLASS_VALUE.

Referenced by cpl_parameterlist_dump().

## cpl_parameter_duplicate()

cpl_parameter * cpl_parameter_duplicate | ( | const cpl_parameter * | self | ) |

Create a copy of a parameter.

Parameters

  self | The parameter to copy.

Returns
  The copy of the given parameter, or `NULL` in case of an error. In the latter case an appropriate error code is set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

The function returns a copy of the parameter self. The copy is a deep copy, i.e. all parameter properties are copied.

References CPL_ERROR_INVALID_TYPE, CPL_ERROR_NULL_INPUT, cpl_error_set, CPL_PARAMETER_CLASS_ENUM, CPL_PARAMETER_CLASS_RANGE, CPL_PARAMETER_CLASS_VALUE, and cpl_parameter_delete().

## cpl_parameter_enable()

cpl_error_code cpl_parameter_enable | ( | cpl_parameter * | self,
|  | cpl_parameter_mode | mode )

Activates a parameter for the given mode.

Parameters

  self | A parameter.
  mode | The parameter mode.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT | The parameter mode mode is not supported.

@enderror

The function enables the parameter self for the given mode mode.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, cpl_parameter_get_name(), CPL_PARAMETER_MODE_CFG, CPL_PARAMETER_MODE_CLI, and CPL_PARAMETER_MODE_ENV.

## cpl_parameter_get_alias()

const char * cpl_parameter_get_alias | ( | const cpl_parameter * | self,
|  | cpl_parameter_mode | mode )

Get the parameter's alias name for the given mode.

Parameters

  self | A parameter.
  mode | The parameter mode.

Returns
  The function returns the parameter's context specific alias name. If no alias name was previously assigned the function returns `NULL`. If an error occurs the function returns `NULL` and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT | The parameter mode mode is not supported.

@enderror

The function retrieves the read-only alias name of the parameter self. The context for which an alias is retrieved is selected by the mode. The functions accepts the parameter modes `CPL_PARAMETER_MODE_CFG`, `CPL_PARAMETER_MODE_CLI` and `CPL_PARAMETER_MODE_ENV`.

See also
  cpl_parameter_mode

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, cpl_parameter_get_name(), CPL_PARAMETER_MODE_CFG, CPL_PARAMETER_MODE_CLI, and CPL_PARAMETER_MODE_ENV.

Referenced by cpl_dfs_setup_product_header().

## cpl_parameter_get_bool()

int cpl_parameter_get_bool | ( | const cpl_parameter * | self | ) |

Get the value of the given boolean parameter.

Parameters

  self | A boolean parameter.

Returns
  The function returns the integer representation of the parameter's boolean value. `TRUE` is represented as non-zero value; whereas 0 indicates `FALSE`. If an error occurs the function returns 0 and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The type of the parameter self is not of type `CPL_TYPE_BOOL`.

The current boolean value of the parameter self is retrieved.

References CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, cpl_parameter_get_name(), cpl_parameter_get_type(), CPL_TYPE_BOOL, and cpl_type_get_name().

Referenced by cpl_dfs_setup_product_header().

## cpl_parameter_get_class()

cpl_parameter_class cpl_parameter_get_class | ( | const cpl_parameter * | self | ) |

Get the parameter's class.

Parameters

  self | A parameter.

Returns
  The function returns the parameter's class identifier. The function returns `CPL_PARAMETER_CLASS_INVALID` if self is not a valid parameter, but `NULL`. In this case an appropriate error code is also set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

The class identifier of the parameter self is retrieved.

References CPL_ERROR_NULL_INPUT, cpl_error_set, and CPL_PARAMETER_CLASS_INVALID.

## cpl_parameter_get_context()

const char * cpl_parameter_get_context | ( | const cpl_parameter * | self | ) |

Get the context of a parameter.

Parameters

  self | A parameter.

Returns
  The function returns the context of the parameter, or `NULL` if self is not a valid parameter but `NULL`. In the latter case an appropriate error code is set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

The function returns the read-only context to which the parameter self belongs. The parameter's context must not be modified using the returned pointer.

References CPL_ERROR_NULL_INPUT, and cpl_error_set.

Referenced by cpl_parameterlist_find_context_const().

## cpl_parameter_get_default_bool()

int cpl_parameter_get_default_bool | ( | const cpl_parameter * | self | ) |

Get the default value of the given boolean parameter.

Parameters

  self | A boolean parameter.

Returns
  The function returns the integer representation of the parameter's default boolean value. `TRUE` is represented as non-zero value; whereas 0 indicates `FALSE`. If an error occurs the function returns 0 and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The type of the parameter self is not of type `CPL_TYPE_BOOL`.

The current boolean default value of the parameter self is retrieved.

References CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, cpl_parameter_get_name(), cpl_parameter_get_type(), CPL_TYPE_BOOL, and cpl_type_get_name().

Referenced by cpl_dfs_setup_product_header().

## cpl_parameter_get_default_double()

double cpl_parameter_get_default_double | ( | const cpl_parameter * | self | ) |

Get the default value of the given double parameter.

Parameters

  self | An double parameter.

Returns
  The function returns the parameter's default double value. If an error occurs the function returns 0 and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The type of the parameter self is not of type `CPL_TYPE_DOUBLE`.

The current double default value of the parameter self is retrieved.

References CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, cpl_parameter_get_name(), cpl_parameter_get_type(), CPL_TYPE_DOUBLE, and cpl_type_get_name().

Referenced by cpl_dfs_setup_product_header().

## cpl_parameter_get_default_flag()

int cpl_parameter_get_default_flag | ( | const cpl_parameter * | self | ) |

Get the presence status flag of the given parameter.

Parameters

  self | A parameter.

Returns
  The function returns the current setting of the parameters presence flag. If the parameter is present the function returns 1 and 0 otherwise. If an error occurs the function returns 0 and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

The function indicates whether the given parameter self was seen by an application while processing the input from the command line, the environment and/or a configuration file. If the parameter was seen the application may set this status flag and query it later using this function.

See also
  cpl_parameter_set_default_flag()

References CPL_ERROR_NULL_INPUT, and cpl_error_set.

## cpl_parameter_get_default_int()

int cpl_parameter_get_default_int | ( | const cpl_parameter * | self | ) |

Get the default value of the given integer parameter.

Parameters

  self | An integer parameter.

Returns
  The function returns the parameter's default integer value. If an error occurs the function returns 0 and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The type of the parameter self is not of type `CPL_TYPE_INT`.

The current integer default value of the parameter self is retrieved.

References CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, cpl_parameter_get_name(), cpl_parameter_get_type(), cpl_type_get_name(), and CPL_TYPE_INT.

Referenced by cpl_dfs_setup_product_header().

## cpl_parameter_get_default_string()

const char * cpl_parameter_get_default_string | ( | const cpl_parameter * | self | ) |

Get the default value of the given string parameter.

Parameters

  self | An string parameter.

Returns
  The function returns the parameter's default string value. If an error occurs the function returns 0 and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The type of the parameter self is not of type `CPL_TYPE_STRING`.

The current read-only string default value of the parameter self is retrieved. If self is not a valid pointer the error code `CPL_ERROR_NULL_INPUT` is set on return. Also, if the parameter self is not an string parameter, i.e. the parameter's type is different from `CPL_TYPE_INT`, the error code `CPL_ERROR_TYPE_MISMATCH` is set.

References CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, cpl_parameter_get_name(), cpl_parameter_get_type(), cpl_type_get_name(), and CPL_TYPE_STRING.

Referenced by cpl_dfs_setup_product_header().

## cpl_parameter_get_double()

double cpl_parameter_get_double | ( | const cpl_parameter * | self | ) |

Get the value of the given double parameter.

Parameters

  self | An double parameter.

Returns
  The function returns the parameter's double value. If an error occurs the function returns 0 and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The type of the parameter self is not of type `CPL_TYPE_INT`.

The current double value of the parameter self is retrieved.

References CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, cpl_parameter_get_name(), cpl_parameter_get_type(), CPL_TYPE_DOUBLE, and cpl_type_get_name().

Referenced by cpl_dfs_setup_product_header().

## cpl_parameter_get_enum_double()

double cpl_parameter_get_enum_double | ( | const cpl_parameter * | self,
|  | int | position )

Get the possible values for a double enumeration.

Parameters

  self | An enumeration parameter
  position | Position to look up in the list of possible values.

Returns
  The double value at position position in the list of possible values of the enumeration self. In case of an error the function returns 0. and an appropriate error code is set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The class of the parameter self is not of the kind `CPL_PARAMETER_CLASS_ENUM`, or self is not of type `CPL_TYPE_DOUBLE`.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | The requested index position position is out of range.

The function retrieves the double value at position position from the list of enumeration values the parameter self can possibly take. For any valid enumeration parameter this list contains at leas one value. The possible values are counted starting from 0.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, CPL_PARAMETER_CLASS_ENUM, cpl_parameter_get_enum_size(), cpl_parameter_get_name(), cpl_parameter_get_type(), CPL_TYPE_DOUBLE, and cpl_type_get_name().

## cpl_parameter_get_enum_int()

int cpl_parameter_get_enum_int | ( | const cpl_parameter * | self,
|  | int | position )

Get the possible values for an integer enumeration.

Parameters

  self | An enumeration parameter
  position | Position to look up in the list of possible values.

Returns
  The integer value at position position in the list of possible values of the enumeration self. In case of an error the function returns 0 and an appropriate error code is set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The class of the parameter self is not of the kind `CPL_PARAMETER_CLASS_ENUM`, or self is not of type `CPL_TYPE_INT`.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | The requested index position position is out of range.

The function retrieves the integer value at position position from the list of enumeration values the parameter self can possibly take. For any valid enumeration parameter this list contains at least one value. The possible values are counted starting from 0.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, CPL_PARAMETER_CLASS_ENUM, cpl_parameter_get_enum_size(), cpl_parameter_get_name(), cpl_parameter_get_type(), cpl_type_get_name(), and CPL_TYPE_INT.

## cpl_parameter_get_enum_size()

int cpl_parameter_get_enum_size | ( | const cpl_parameter * | self | ) |

Get the number of alternatives of an enumeration parameter.

Parameters

  self | An enumeration parameter.

Returns
  The number of possible values the parameter self can take, or 0 if self does not point to a valid parameter, or the parameter is not an enumeration parameter. In case of an error the function also sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The class of the parameter self is not of the kind `CPL_PARAMETER_CLASS_ENUM`.

The function retrieves the number of possible alternatives for an enumeration parameter, which is always greater or equal than 1.

References CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, CPL_PARAMETER_CLASS_ENUM, cpl_parameter_get_name(), cpl_parameter_get_type(), and cpl_type_get_name().

Referenced by cpl_parameter_get_enum_double(), cpl_parameter_get_enum_int(), and cpl_parameter_get_enum_string().

## cpl_parameter_get_enum_string()

const char * cpl_parameter_get_enum_string | ( | const cpl_parameter * | self,
|  | int | position )

Get the possible values for a string enumeration.

Parameters

  self | An enumeration parameter
  position | Position to look up in the list of possible values.

Returns
  The string value at position position in the list of possible values of the enumeration self. In case of an error the function returns `NULL` and an appropriate error code is set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The class of the parameter self is not of the kind `CPL_PARAMETER_CLASS_ENUM`, or self is not of type `CPL_TYPE_STRING`.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | The requested index position position is out of range.

The function retrieves the read-only string value at position position from the list of enumeration values the parameter self can possibly take. For any valid enumeration parameter this list contains at least one value. The possible values are counted starting from 0.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, CPL_PARAMETER_CLASS_ENUM, cpl_parameter_get_enum_size(), cpl_parameter_get_name(), cpl_parameter_get_type(), cpl_type_get_name(), and CPL_TYPE_STRING.

## cpl_parameter_get_help()

const char * cpl_parameter_get_help | ( | const cpl_parameter * | self | ) |

Get the description of a parameter.

Parameters

  self | A parameter.

Returns
  The function returns the parameter description, or `NULL` if no description has been set. The function returns `NULL` if an error occurs and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

The function returns the read-only short help of the parameter self. The parameter description must not be modified using the returned pointer.

References CPL_ERROR_NULL_INPUT, and cpl_error_set.

Referenced by cpl_dfs_setup_product_header().

## cpl_parameter_get_id()

int cpl_parameter_get_id | ( | const cpl_parameter * | self | ) |

Change the presence status flag of the given parameter.

Parameters

  self | A parameter.
  status | The presence status value to assign.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

The function sets the presence status flag of the given parameter self to the value status. Any non-zero value means that the parameter is present. If the presence status should be changed to `not present' the argument status must be 0.

See also
  cpl_parameter_get_default_flag() */

cpl_error_code cpl_parameter_set_default_flag(cpl_parameter *self, int status) { if (self == NULL) { return cpl_error_set(cpl_func, CPL_ERROR_NULL_INPUT); }

self->info.present = status == 0 ? FALSE : TRUE; return CPL_ERROR_NONE; }

/**

Get the numerical identifier of the given parameter.

Parameters

  self | A parameter.

Returns
  The function returns the parameter's numerical identifier. If an error occurs the function returns 0 and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

The function looks up the numerical identifier of the given parameter self. A numerical identifier may be assigned to a parameter using cpl_parameter_set_id().

See also
  cpl_parameter_set_id()

References CPL_ERROR_NULL_INPUT, and cpl_error_set.

## cpl_parameter_get_int()

int cpl_parameter_get_int | ( | const cpl_parameter * | self | ) |

Get the value of the given integer parameter.

Parameters

  self | An integer parameter.

Returns
  The function returns the parameter's integer value. If an error occurs the function returns 0 and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The type of the parameter self is not of type `CPL_TYPE_INT`.

The current integer value of the parameter self is retrieved.

References CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, cpl_parameter_get_name(), cpl_parameter_get_type(), cpl_type_get_name(), and CPL_TYPE_INT.

Referenced by cpl_dfs_setup_product_header().

## cpl_parameter_get_name()

const char * cpl_parameter_get_name | ( | const cpl_parameter * | self | ) |

Get the name of a parameter.

Parameters

  self | A parameter.

Returns
  The function returns the parameter's unique name, or `NULL` if self is not a valid parameter but `NULL`. In the latter case an appropriate error code is set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

The function returns the read-only unique name of the parameter self. The parameter name must not be modified using the returned pointer.

References CPL_ERROR_NULL_INPUT, and cpl_error_set.

Referenced by cpl_parameter_disable(), cpl_parameter_enable(), cpl_parameter_get_alias(), cpl_parameter_get_bool(), cpl_parameter_get_default_bool(), cpl_parameter_get_default_double(), cpl_parameter_get_default_int(), cpl_parameter_get_default_string(), cpl_parameter_get_double(), cpl_parameter_get_enum_double(), cpl_parameter_get_enum_int(), cpl_parameter_get_enum_size(), cpl_parameter_get_enum_string(), cpl_parameter_get_int(), cpl_parameter_get_range_max_double(), cpl_parameter_get_range_max_int(), cpl_parameter_get_range_min_double(), cpl_parameter_get_range_min_int(), cpl_parameter_get_string(), cpl_parameter_is_enabled(), cpl_parameter_set_alias(), cpl_parameter_set_bool(), cpl_parameter_set_default_bool(), cpl_parameter_set_default_double(), cpl_parameter_set_default_int(), cpl_parameter_set_default_string(), cpl_parameter_set_double(), cpl_parameter_set_int(), cpl_parameter_set_string(), and cpl_parameterlist_find_const().

## cpl_parameter_get_range_max_double()

double cpl_parameter_get_range_max_double | ( | const cpl_parameter * | self | ) |

Get the maximum value of a double range parameter.

Parameters

  self | A double range parameter.

Returns
  The function returns the maximum double value the range parameter self can take. In case of an error, the function returns 0. and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The class of the parameter self is not of the kind `CPL_PARAMETER_CLASS_RANGE`, or self is not of type `CPL_TYPE_DOUBLE`.

The function retrieves the double value defined to be the upper limit of the double range parameter self.

References CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, CPL_PARAMETER_CLASS_RANGE, cpl_parameter_get_name(), cpl_parameter_get_type(), CPL_TYPE_DOUBLE, and cpl_type_get_name().

## cpl_parameter_get_range_max_int()

int cpl_parameter_get_range_max_int | ( | const cpl_parameter * | self | ) |

Get the maximum value of an integer range parameter.

Parameters

  self | An integer range parameter.

Returns
  The function returns the maximum integer value the range parameter self can take. In case of an error, the function returns 0 and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The class of the parameter self is not of the kind `CPL_PARAMETER_CLASS_RANGE`, or self is not of type `CPL_TYPE_INT`.

The function retrieves the integer value defined to be the upper limit of the integer range parameter self.

References CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, CPL_PARAMETER_CLASS_RANGE, cpl_parameter_get_name(), cpl_parameter_get_type(), cpl_type_get_name(), and CPL_TYPE_INT.

## cpl_parameter_get_range_min_double()

double cpl_parameter_get_range_min_double | ( | const cpl_parameter * | self | ) |

Get the minimum value of a double range parameter.

Parameters

  self | A double range parameter.

Returns
  The function returns the minimum double value the range parameter self can take. In case of an error, the function returns 0. and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The class of the parameter self is not of the kind `CPL_PARAMETER_CLASS_RANGE`, or self is not of type `CPL_TYPE_DOUBLE`.

The function retrieves the double value defined to be the lower limit of the double range parameter self.

References CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, CPL_PARAMETER_CLASS_RANGE, cpl_parameter_get_name(), cpl_parameter_get_type(), CPL_TYPE_DOUBLE, and cpl_type_get_name().

## cpl_parameter_get_range_min_int()

int cpl_parameter_get_range_min_int | ( | const cpl_parameter * | self | ) |

Get the minimum value of an integer range parameter.

Parameters

  self | An integer range parameter.

Returns
  The function returns the minimum integer value the range parameter self can take. In case of an error, the function returns 0 and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The class of the parameter self is not of the kind `CPL_PARAMETER_CLASS_RANGE`, or self is not of type `CPL_TYPE_INT`.

The function retrieves the integer value defined to be the lower limit of the integer range parameter self.

References CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, CPL_PARAMETER_CLASS_RANGE, cpl_parameter_get_name(), cpl_parameter_get_type(), cpl_type_get_name(), and CPL_TYPE_INT.

## cpl_parameter_get_string()

const char * cpl_parameter_get_string | ( | const cpl_parameter * | self | ) |

Get the value of the given string parameter.

Parameters

  self | A string parameter.

Returns
  The function returns the parameter's string value. If an error occurs the function returns `NULL` and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The type of the parameter self is not of type `CPL_TYPE_STRING`.

The current string value of the parameter self is retrieved.

References CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, cpl_parameter_get_name(), cpl_parameter_get_type(), cpl_type_get_name(), and CPL_TYPE_STRING.

Referenced by cpl_dfs_setup_product_header().

## cpl_parameter_get_tag()

const char * cpl_parameter_get_tag | ( | const cpl_parameter * | self | ) |

Get the parameter's user tag.

Parameters

  self | A parameter.

Returns
  The function returns the parameter's user tag, or `NULL` if no user tag was previously set. The function returns `NULL` if an error occurs and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

The current read-only setting of the user definable tag of the given parameter self is retrieved.

References CPL_ERROR_NULL_INPUT, and cpl_error_set.

Referenced by cpl_parameterlist_find_tag_const().

## cpl_parameter_get_type()

cpl_type cpl_parameter_get_type | ( | const cpl_parameter * | self | ) |

Get the parameter's value type.

Parameters

  self | A parameter.

Returns
  The function returns the parameter's value type. The function returns `CPL_TYPE_INVALID` if self is not a valid parameter, but `NULL`. In this case an appropriate error is also set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

The type identifier of the parameter's value is retrieved from the given parameter self.

References CPL_ERROR_NULL_INPUT, cpl_error_set, and CPL_TYPE_INVALID.

Referenced by cpl_dfs_setup_product_header(), cpl_parameter_get_bool(), cpl_parameter_get_default_bool(), cpl_parameter_get_default_double(), cpl_parameter_get_default_int(), cpl_parameter_get_default_string(), cpl_parameter_get_double(), cpl_parameter_get_enum_double(), cpl_parameter_get_enum_int(), cpl_parameter_get_enum_size(), cpl_parameter_get_enum_string(), cpl_parameter_get_int(), cpl_parameter_get_range_max_double(), cpl_parameter_get_range_max_int(), cpl_parameter_get_range_min_double(), cpl_parameter_get_range_min_int(), cpl_parameter_get_string(), cpl_parameter_set_bool(), cpl_parameter_set_default_bool(), cpl_parameter_set_default_double(), cpl_parameter_set_default_int(), cpl_parameter_set_default_string(), cpl_parameter_set_double(), cpl_parameter_set_int(), cpl_parameter_set_string(), and cpl_parameterlist_find_type_const().

## cpl_parameter_is_enabled()

int cpl_parameter_is_enabled | ( | const cpl_parameter * | self,
|  | cpl_parameter_mode | mode )

Get the parameter's activity status for the environment context.

Parameters

  self | A parameter.
  mode | The parameter mode.

Returns
  The function returns a non-zero value if the parameter is enabled for the environment context, or 0 if the parameter is not active. If an error occurs the function returns 0 and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT | The parameter mode mode is not supported.

@enderror

The function returns whether the parameter is enabled for the environment context or not. If the parameter is enabled for the context the application may modify the parameter's value if the parameter is referenced in the context specific input of the application. If the parameter is disabled, the application must not modify the parameter's value.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, cpl_parameter_get_name(), CPL_PARAMETER_MODE_CFG, CPL_PARAMETER_MODE_CLI, and CPL_PARAMETER_MODE_ENV.

## cpl_parameter_new_enum()

cpl_parameter * cpl_parameter_new_enum | ( | const char * | name,
|  | cpl_type | type,
|  | const char * | description,
|  | const char * | context,
|  |  | ... )

Create a new enumeration parameter.

Parameters

  name | The parameter's unique name
  type | The type of the parameter's current and default value.
  description | An optional comment or description of the parameter.
  context | The context to which the parameter belongs.
  ... | Arguments used for parameter initialisation.

Returns
  The function returns the newly created parameter, or `NULL` if the parameter could not be created. In the latter case an appropriate error code is set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter name is a NULL pointer.
  CPL_ERROR_INVALID_TYPE | An unsupported type was passed as type.
  CPL_ERROR_ILLEGAL_INPUT | The provided parameter initialisation data is invalid.

The function allocates memory for an enumeration parameter with the name name and a value type type. Optionally a comment describing the parameter may be passed by description and the context to which the parameter belongs may be given by context.

To properly initialise the newly created enumeration, the parameter's default value (together with the number of alternatives following) and the list of enumeration alternatives must be passed as the variable argument list arguments. The list of enumeration alternatives must contain the default value! Apart from the number of possible alternatives, which must be an argument of type `int`, the type of all initialisation arguments must match the parameter's value type as it is indicated by type. Enumeration parameters can only be created for the value types integer, double or string.

The following example creates a string enumeration parameter with the unique name `application.setup.enum` which belongs to the context `application.setup` with the default `first` and 3 enumeration alternatives.

Example:
  const char *first = "first";
  const char *second = "second";
  const char *third = "third";
  cpl_parameter *p = cpl_parameter_new_enum("application.setup.enum",
  CPL_TYPE_STRING,
  "An enum of type string",
  "application.setup",
  first, 3, first, second,
  third);

See also
  cpl_parameter_new_value(), cpl_parameter_new_range(), cpl_parameter_new_enum_from_array()

References CPL_ERROR_INVALID_TYPE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_PARAMETER_CLASS_ENUM, cpl_parameter_delete(), CPL_TYPE_BOOL, and cpl_type_get_name().

## cpl_parameter_new_enum_from_array()

cpl_parameter * cpl_parameter_new_enum_from_array | ( | const char * | name,
|  | cpl_type | type,
|  | const char * | description,
|  | const char * | context,
|  | cpl_size | position,
|  | cpl_size | size,
|  | const void * | alternatives )

Create a new enumeration parameter from an array of alternative values.

Parameters

  name | The parameter's unique name
  type | The type of the parameter's current and default value.
  description | An optional comment or description of the parameter.
  context | The context to which the parameter belongs.
  position | The index of the alternative to use as default value.
  size | The size of the enumeration alternatives list.
  alternatives | The array of enumeration alternatives.

Returns
  The function returns the newly created parameter, or `NULL` if the parameter could not be created. In the latter case an appropriate error code is set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter name is a NULL pointer.
  CPL_ERROR_INVALID_TYPE | An unsupported type was passed as type.
  CPL_ERROR_ILLEGAL_INPUT | The provided parameter initialisation data is invalid.

The function allocates memory for an enumeration parameter with the name name and a value type type. Optionally a comment describing the parameter may be passed by description and the context to which the parameter belongs may be given by context.

To properly initialise the newly created enumeration the index position of the parameter's default value in the array of alternatives alternatives must be given. The size of the array of alternatives is given by size. The type of all alternatives given must match the parameter's value type as it is indicated by type. Enumeration parameters can only be created for the value types integer, double or string.

The following example creates a string enumeration parameter with the unique name `application.setup.enum` which belongs to the context `application.setup` with the default `first` and 3 enumeration alternatives.

Example:
  const char *alternatives = {"first", "second", "third"};
  cpl_parameter *p =
  cpl_parameter_new_enum_array_from_array("application.setup.enum",
  CPL_TYPE_STRING,
  "An enum of type string",
  "application.setup",
  0, 3, alternatives);

See also
  cpl_parameter_new_value(), cpl_parameter_new_range(), cpl_parameter_new_enum()

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INVALID_TYPE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_PARAMETER_CLASS_ENUM, CPL_TYPE_BOOL, CPL_TYPE_FLAG_ARRAY, cpl_type_get_name(), and cpl_type_get_sizeof().

## cpl_parameter_new_range()

cpl_parameter * cpl_parameter_new_range | ( | const char * | name,
|  | cpl_type | type,
|  | const char * | description,
|  | const char * | context,
|  |  | ... )

Create a new range parameter.

Parameters

  name | The parameter's unique name
  type | The type of the parameter's current and default value.
  description | An optional comment or description of the parameter.
  context | The context to which the parameter belongs.
  ... | Arguments used for parameter initialisation.

Returns
  The function returns the newly created parameter, or `NULL` if the parameter could not be created. In the latter case an appropriate error code is set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter name is a NULL pointer.
  CPL_ERROR_INVALID_TYPE | An unsupported type was passed as type.
  CPL_ERROR_ILLEGAL_INPUT | The provided parameter initialisation data is invalid.

The function allocates memory for a range parameter with the name name and a value type type. Optionally a comment describing the parameter may be passed by description and the context to which the parameter belongs may be given by context.

To properly initialise the newly created range the parameters default value together with the minimum and maximum value of the range has to be passed as the variable argument list arguments. The type of all initialisation arguments must match the parameter's value type as it is indicated by type. Range parameters can only be created for the value types integer or double.

The following example creates a double range parameter with the unique name `application.setup.range` which belongs to the context `application.setup` with the default `def` and the range boundary values minimum and maximum.

Example:
  double def = 0.5;
  double min = 0.0;
  double max = 1.0;
  cpl_parameter *p = cpl_parameter_new_range("application.setup.range",
  CPL_TYPE_DOUBLE,
  "A range of type double",
  "application.setup",
  def, min, max);

See also
  cpl_parameter_new_value(), cpl_parameter_new_enum()

References CPL_ERROR_INVALID_TYPE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_PARAMETER_CLASS_RANGE, cpl_parameter_delete(), CPL_TYPE_BOOL, cpl_type_get_name(), and CPL_TYPE_STRING.

## cpl_parameter_new_value()

cpl_parameter * cpl_parameter_new_value | ( | const char * | name,
|  | cpl_type | type,
|  | const char * | description,
|  | const char * | context,
|  |  | ... )

Create a new value parameter.

Parameters

  name | The parameter's unique name
  type | The type of the parameter's current and default value.
  description | An optional comment or description of the parameter.
  context | The context to which the parameter belongs.
  ... | Arguments used for parameter initialisation.

Returns
  The function returns the newly created parameter, or `NULL` if the parameter could not be created. In the latter case an appropriate error code is set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter name is a NULL pointer.
  CPL_ERROR_INVALID_TYPE | An unsupported type was passed as type.
  CPL_ERROR_ILLEGAL_INPUT | The provided parameter initialisation data is invalid.

The function allocates memory for a value parameter with the name name and a value type type. Optionally a comment describing the parameter may be passed by description and the context to which the parameter belongs may be given by context.

The newly created parameter is initialised with the default value passed to the function as the only variable argument list argument. The type of the value must match the parameter's value type as it is indicated by type.

The following example creates an integer value parameter with the unique name `application.setup.value` which belongs to the context `application.setup` with the default value `def`

Example:
  int def = 1;
  cpl_parameter *p = cpl_parameter_new_value("application.setup.value",
  CPL_TYPE_INT,
  "An integer value",
  "application.setup",
  def);

See also
  cpl_parameter_new_range(), cpl_parameter_new_enum()

References CPL_ERROR_INVALID_TYPE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_PARAMETER_CLASS_VALUE, cpl_parameter_delete(), and cpl_type_get_name().

## cpl_parameter_set_alias()

cpl_error_code cpl_parameter_set_alias | ( | cpl_parameter * | self,
|  | cpl_parameter_mode | mode,
|  | const char * | alias )

Set alias names for the given parameter.

Parameters

  self | A parameter
  mode | The parameter mode for which the alias should be set.
  alias | The parameter's alias.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT | The parameter mode mode is not supported.

@enderror

The function assigns an alternative name to the parameter self for the given mode mode. This alias name may be used instead of the fully qualified parameter name in the context for which they have been set. If the alias name is `NULL` a previously set alias is deleted.

The context for which an alias is set is selected by the mode. The functions accepts the parameter modes `CPL_PARAMETER_MODE_CFG`, `CPL_PARAMETER_MODE_CLI` and `CPL_PARAMETER_MODE_ENV`.

See also
  cpl_parameter_mode

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, cpl_parameter_get_name(), CPL_PARAMETER_MODE_CFG, CPL_PARAMETER_MODE_CLI, and CPL_PARAMETER_MODE_ENV.

## cpl_parameter_set_bool()

cpl_error_code cpl_parameter_set_bool | ( | cpl_parameter * | self,
|  | int | value )

Assign a boolean value to a parameter.

Parameters

  self | The parameter the value is assigned to.
  value | The boolean value to be assigned.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The type of the parameter self is not of type `CPL_TYPE_BOOL`.

The function assigns a boolean value value to a parameter of type `CPL_TYPE_BOOL`. Any non-zero value passed as value is interpreted as true.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, cpl_parameter_get_name(), cpl_parameter_get_type(), CPL_TYPE_BOOL, and cpl_type_get_name().

## cpl_parameter_set_default_bool()

cpl_error_code cpl_parameter_set_default_bool | ( | cpl_parameter * | self,
|  | int | value )

Modify the default value of a boolean parameter.

Parameters

  self | The parameter whose default value is modified.
  value | The boolean value to be assigned.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The type of the parameter self is not of type `CPL_TYPE_BOOL`.

The function changes the default value of the parameter self to the boolean value value. The parameter self must be of type `CPL_TYPE_BOOL`. Any non-zero value passed as value is interpreted as true.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, cpl_parameter_get_name(), cpl_parameter_get_type(), CPL_TYPE_BOOL, and cpl_type_get_name().

## cpl_parameter_set_default_double()

cpl_error_code cpl_parameter_set_default_double | ( | cpl_parameter * | self,
|  | double | value )

Modify the default value of a double parameter.

Parameters

  self | The parameter whose default value is modified.
  value | The double value to be assigned.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The type of the parameter self is not of type `CPL_TYPE_DOUBLE`.

The function changes the default value of the parameter self to the double value value. The parameter self must be of type `CPL_TYPE_DOUBLE`.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, cpl_parameter_get_name(), cpl_parameter_get_type(), CPL_TYPE_DOUBLE, and cpl_type_get_name().

## cpl_parameter_set_default_int()

cpl_error_code cpl_parameter_set_default_int | ( | cpl_parameter * | self,
|  | int | value )

Modify the default value of an integer parameter.

Parameters

  self | The parameter whose default value is modified.
  value | The integer value to be assigned.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The type of the parameter self is not of type `CPL_TYPE_INT`.

The function changes the default value of the parameter self to the integer value value. The parameter self must be of type `CPL_TYPE_INT`.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, cpl_parameter_get_name(), cpl_parameter_get_type(), cpl_type_get_name(), and CPL_TYPE_INT.

## cpl_parameter_set_default_string()

cpl_error_code cpl_parameter_set_default_string | ( | cpl_parameter * | self,
|  | const char * | value )

Modify the default value of a string parameter.

Parameters

  self | The parameter whose default value is modified.
  value | The string value to be assigned.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The type of the parameter self is not of type `CPL_TYPE_STRING`.

The function changes the default value of the parameter self to the string value value. The parameter self must be of type `CPL_TYPE_STRING`.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, cpl_parameter_get_name(), cpl_parameter_get_type(), cpl_type_get_name(), and CPL_TYPE_STRING.

## cpl_parameter_set_double()

cpl_error_code cpl_parameter_set_double | ( | cpl_parameter * | self,
|  | double | value )

Assign a double value to a parameter.

Parameters

  self | The parameter the value is assigned to.
  value | The double value to be assigned.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The type of the parameter self is not of type `CPL_TYPE_DOUBLE`.

The function assigns a double value value to a parameter of type `CPL_TYPE_DOUBLE`.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, cpl_parameter_get_name(), cpl_parameter_get_type(), CPL_TYPE_DOUBLE, and cpl_type_get_name().

## cpl_parameter_set_id()

cpl_error_code cpl_parameter_set_id | ( | cpl_parameter * | self,
|  | int | id )

Set the numerical identifier of the given parameter.

Parameters

  self | A parameter.
  id | Numerical identifier to assign.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

The function assigns a numerical identifier to the parameter self. The numerical value to be assigned to the parameter's numerical identifier member is passed as the argument id. The function does not do any checks on the numerical value of id. The numerical identifier may be used by an application to, for instance, assign a sequence number to the parameter.

See also
  cpl_parameter_get_id()

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_error_set.

## cpl_parameter_set_int()

cpl_error_code cpl_parameter_set_int | ( | cpl_parameter * | self,
|  | int | value )

Assign an integer value to a parameter.

Parameters

  self | The parameter the value is assigned to.
  value | The integer value to be assigned.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The type of the parameter self is not of type `CPL_TYPE_INT`.

The function assigns an integer value value to a parameter of type `CPL_TYPE_INT`.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, cpl_parameter_get_name(), cpl_parameter_get_type(), cpl_type_get_name(), and CPL_TYPE_INT.

## cpl_parameter_set_string()

cpl_error_code cpl_parameter_set_string | ( | cpl_parameter * | self,
|  | const char * | value )

Assign a string value to a parameter.

Parameters

  self | The parameter the value is assigned to.
  value | The string value to be assigned.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_TYPE_MISMATCH | The type of the parameter self is not of type `CPL_TYPE_STRING`.

The function assigns a string value value to a parameter of type `CPL_TYPE_STRING`.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, cpl_parameter_get_name(), cpl_parameter_get_type(), cpl_type_get_name(), and CPL_TYPE_STRING.

## cpl_parameter_set_tag()

cpl_error_code cpl_parameter_set_tag | ( | cpl_parameter * | self,
|  | const char * | tag )

Set the tag of the given parameter.

Parameters

  self | A parameter.
  tag | Tag string to assign.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

The function assigns a user definable tag tag to the parameter self. The function does not check the passed string tag in any way. The tag may be used by an application but it cannot rely on the contents of the parameter's tag.

See also
  cpl_parameter_get_tag()

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_error_set.