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_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) |
| Get the numerical identifier 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_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_flag (cpl_parameter *self, int status) |
| Change the presence status flag of the given 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 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 for a range expects the default value, the minimum and the maximum value. The constructor for an enumeration expects as arguments the default value, the number of alternatives following and the list of alternatives. Note that the default value must be a member of the list of alternative enumeration values.
An example of how parameters of the different classes are created and destroyed is shown below:
...
"This is a plain value of type integer",
"Example",
-1);
"This is a value range of type double",
"Example",
0.5, 0.0, 1.0);
"This is an enumeration of type "
"string",
"Example",
"first", 3, "first", "second",
"third");
...
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.
- Synopsis:
#include <cpl_parameter.h>
Typedef Documentation
The opaque parameter data type.
The parameter class data type.
The parameter mode data type.
Enumeration Type Documentation
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.
|
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
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.
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.
- Errors:
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
CPL_ERROR_ILLEGAL_INPUT | The parameter mode mode is not supported. |
The function disables the parameter self for the given mode mode.
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.
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.
- Errors:
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
CPL_ERROR_ILLEGAL_INPUT | The parameter mode mode is not supported. |
The function enables the parameter self for the given 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.
- Errors:
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
CPL_ERROR_ILLEGAL_INPUT | The parameter mode mode is not supported. |
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
Get the value of the given boolean parameter.
- Parameters:
-
- 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.
Get the parameter's class.
- Parameters:
-
- 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.
const char* cpl_parameter_get_context |
( |
const cpl_parameter * |
self | ) |
|
Get the context of a parameter.
- Parameters:
-
- 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.
Get the default value of the given boolean parameter.
- Parameters:
-
- 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.
double cpl_parameter_get_default_double |
( |
const cpl_parameter * |
self | ) |
|
Get the default value of the given double parameter.
- Parameters:
-
- 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.
Get the presence status flag of the given parameter.
- Parameters:
-
- 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()
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.
const char* cpl_parameter_get_default_string |
( |
const cpl_parameter * |
self | ) |
|
Get the default value of the given string parameter.
- Parameters:
-
- 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.
Get the value of the given double parameter.
- Parameters:
-
- 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.
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.
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.
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.
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.
Get the description of a parameter.
- Parameters:
-
- 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.
Get the numerical identifier of the given parameter.
- Parameters:
-
- Returns:
- The function returns the parameter's numerical identifier. 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 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()
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.
Get the name of a parameter.
- Parameters:
-
- 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.
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.
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.
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.
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.
const char* cpl_parameter_get_string |
( |
const cpl_parameter * |
self | ) |
|
Get the value of the given string parameter.
- Parameters:
-
- 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.
Get the parameter's user tag.
- Parameters:
-
- 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.
- Errors:
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
The current read-only setting of the user definable tag of the given parameter self is retrieved.
Get the parameter's value type.
- Parameters:
-
- 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.
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.
- Errors:
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
CPL_ERROR_ILLEGAL_INPUT | The parameter mode mode is not supported. |
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.
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 self is a NULL pointer. |
CPL_ERROR_INVALID_TYPE | An unsupported type was passed as type. |
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.
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 def and 3 enumeration alternatives.
- Example:
const char *first = "first";
const char *second = "second";
const char *third = "third";
"An enum of type string",
"application.setup",
first, 3, first, second,
third);
- See also:
- cpl_parameter_new_value(), 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 self is a NULL pointer. |
CPL_ERROR_INVALID_TYPE | An unsupported type was passed as type. |
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.
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;
"A range of type double",
"application.setup",
def, min, max);
- See also:
- cpl_parameter_new_value(), cpl_parameter_new_enum()
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. |
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;
"An integer value",
"application.setup",
def);
- See also:
- cpl_parameter_new_range(), cpl_parameter_new_enum()
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.
- Errors:
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
CPL_ERROR_ILLEGAL_INPUT | The parameter mode mode is not supported. |
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
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.
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.
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
.
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()
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
.
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
.
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
.
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.
- Errors:
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
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()
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
.
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
.
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.
- Errors:
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
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()