Typedefs | |
typedef enum _cpl_parameter_mode_ | cpl_parameter_mode |
The parameter mode data type. | |
typedef enum _cpl_parameter_class_ | cpl_parameter_class |
The parameter class data type. | |
typedef _cpl_parameter_ | cpl_parameter |
The opaque parameter data type. | |
Enumerations | |
enum | _cpl_parameter_mode_ { CPL_PARAMETER_MODE_CLI, CPL_PARAMETER_MODE_ENV, CPL_PARAMETER_MODE_CFG } |
Supported parameter modes. More... | |
enum | _cpl_parameter_class_ { CPL_PARAMETER_CLASS_INVALID, CPL_PARAMETER_CLASS_VALUE, CPL_PARAMETER_CLASS_RANGE, CPL_PARAMETER_CLASS_ENUM } |
Supported parameter classes. More... | |
Functions | |
cpl_parameter * | cpl_parameter_new_value (const char *name, cpl_type type, const char *description, const char *context,...) |
Create a new value 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_enum (const char *name, cpl_type type, const char *description, const char *context,...) |
Create a new enumeration parameter. | |
void | cpl_parameter_delete (cpl_parameter *self) |
Delete a 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_int (cpl_parameter *self, int value) |
Assign an integer value to a 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_string (cpl_parameter *self, const char *value) |
Assign a string value to a parameter. | |
const char * | cpl_parameter_get_name (const cpl_parameter *self) |
Get the name of a parameter. | |
const char * | cpl_parameter_get_context (const cpl_parameter *self) |
Get the context of a parameter. | |
const char * | cpl_parameter_get_help (const cpl_parameter *self) |
Get the description of a parameter. | |
cpl_type | cpl_parameter_get_type (const cpl_parameter *self) |
Get the parameter's value type. | |
cpl_parameter_class | cpl_parameter_get_class (const cpl_parameter *self) |
Get the parameter's class. | |
int | cpl_parameter_get_bool (const cpl_parameter *self) |
Get the value of the given boolean parameter. | |
int | cpl_parameter_get_int (const cpl_parameter *self) |
Get the value of the given integer parameter. | |
double | cpl_parameter_get_double (const cpl_parameter *self) |
Get the value of the given double parameter. | |
const char * | cpl_parameter_get_string (const cpl_parameter *self) |
Get the value of the given string parameter. | |
int | cpl_parameter_get_default_bool (const cpl_parameter *self) |
Get the default value of the given boolean parameter. | |
int | cpl_parameter_get_default_int (const cpl_parameter *self) |
Get the default value of the given integer parameter. | |
double | cpl_parameter_get_default_double (const cpl_parameter *self) |
Get the default value of the given double parameter. | |
const char * | cpl_parameter_get_default_string (const cpl_parameter *self) |
Get the default value of the given string parameter. | |
int | cpl_parameter_get_enum_size (const cpl_parameter *self) |
Get the number of alternatives of an enumeration parameter. | |
int | cpl_parameter_get_enum_int (const cpl_parameter *self, int index) |
Get the possible values for an integer enumeration. | |
double | cpl_parameter_get_enum_double (const cpl_parameter *self, int index) |
Get the possible values for a double enumeration. | |
const char * | cpl_parameter_get_enum_string (const cpl_parameter *self, int index) |
Get the possible values for a string enumeration. | |
int | cpl_parameter_get_range_min_int (const cpl_parameter *self) |
Get the minimum 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_max_int (const cpl_parameter *self) |
Get the maximum value of an integer range 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_default_flag (const cpl_parameter *self) |
Get the presence status flag of the given parameter. | |
cpl_error_code | cpl_parameter_set_default_flag (cpl_parameter *self, int status) |
Change the presence status flag of the given parameter. | |
int | cpl_parameter_get_id (const cpl_parameter *self) |
Get the numerical identifier of the given parameter. | |
cpl_error_code | cpl_parameter_set_id (cpl_parameter *self, int id) |
Set the numerical identifier of the given parameter. | |
const char * | cpl_parameter_get_tag (const cpl_parameter *self) |
Get the parameter's user tag. | |
cpl_error_code | cpl_parameter_set_tag (cpl_parameter *self, const char *tag) |
Set the tag of the given 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. | |
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_is_enabled (const cpl_parameter *self, cpl_parameter_mode mode) |
Get the parameter's activity status for the environment context. | |
cpl_error_code | cpl_parameter_enable (cpl_parameter *self, cpl_parameter_mode mode) |
Activates a parameter for the given mode. | |
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. |
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:
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.
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:
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);
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.
#include <cpl_parameter.h>
|
The opaque parameter data type.
|
|
The parameter class data type.
|
|
The parameter mode data type.
|
|
Supported parameter classes.
|
|
Supported parameter modes. The parameter mode is used to set or get context specific parameter attributes. |
|
Delete a parameter.
|
|
Deactivate a parameter for the given mode.
The function disables the parameter self for the given mode mode. |
|
Dump the parameter debugging information to the given stream.
NULL the function writes to the standard output. If self is NULL the function does nothing. |
|
Activates a parameter for the given mode.
The function enables the parameter self for the given mode mode. |
|
Get the parameter's alias name for the given mode.
The function retrieves the 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
|
|
Get the value of the given boolean parameter.
The current boolean value of the parameter self is retrieved. |
|
Get the parameter's class.
The class identifier of the parameter self is retrieved. |
|
Get the context of a parameter.
The function returns the 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.
The current boolean default value of the parameter self is retrieved. |
|
Get the default value of the given double parameter.
The current double default value of the parameter self is retrieved. |
|
Get the presence status flag of the given parameter.
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.
|
|
Get the default value of the given integer parameter.
The current integer default value of the parameter self is retrieved. |
|
Get the default value of the given string parameter.
The current string default value of the parameter self is retrieved. If self is not a valid pointer the error code |
|
Get the value of the given double parameter.
The current double value of the parameter self is retrieved. |
|
Get the possible values for a double enumeration.
The function retrieves the double value at position index 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. |
|
Get the possible values for an integer enumeration.
The function retrieves the integer value at position index 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.
The function retrieves the number of possible alternatives for an enumeration parameter, which is always greater or equal than 1. |
|
Get the possible values for a string enumeration.
The function retrieves the string value at position index 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. |
|
Get the description of a parameter.
The function returns the 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.
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().
|
|
Get the value of the given integer parameter.
The current integer value of the parameter self is retrieved. |
|
Get the name of a parameter.
The function returns the unique name of the parameter self. The parameter name must not be modified using the returned pointer. |
|
Get the maximum value of a double range parameter.
The function retrieves the double value defined to be the upper limit of the double range parameter self. |
|
Get the maximum value of an integer range parameter.
The function retrieves the integer value defined to be the upper limit of the integer range parameter self. |
|
Get the minimum value of a double range parameter.
The function retrieves the double value defined to be the lower limit of the double range parameter self. |
|
Get the minimum value of an integer range parameter.
The function retrieves the integer value defined to be the lower limit of the integer range parameter self. |
|
Get the value of the given string parameter.
The current string value of the parameter self is retrieved. |
|
Get the parameter's user tag.
The current setting of the user definable tag of the given parameter self is retrieved. |
|
Get the parameter's value type.
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.
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. |
|
Create a new enumeration parameter.
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
The following example creates a string enumeration parameter with the unique name
|
|
Create a new range parameter.
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
|
|
Create a new value parameter.
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
|
|
Set alias names for the given parameter.
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
The context for which an alias is set is selected by the mode. The functions accepts the parameter modes
|
|
Assign a boolean value to a parameter.
The function assigns a boolean value value to a parameter of type |
|
Change the presence status flag of the given parameter.
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.
|
|
Assign a double value to a parameter.
The function assigns a double value value to a parameter of type |
|
Set the numerical identifier of the given parameter.
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.
|
|
Assign an integer value to a parameter.
The function assigns an integer value value to a parameter of type |
|
Assign a string value to a parameter.
The function assigns a string value value to a parameter of type |
|
Set the tag of the given parameter.
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.
|