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_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:

       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.

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

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.

Enumeration Type Documentation

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.

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

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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()

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.

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.

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.

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.

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.

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.

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.

int cpl_parameter_get_id ( const cpl_parameter * self )

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.

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()

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.

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.

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:

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.

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.

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.

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.

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.

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";

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* 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;

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()

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;

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()

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.

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

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.

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.

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.

cpl_error_code cpl_parameter_set_default_flag	(	cpl_parameter *	self,
		int	status
	)

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_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.

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.

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.

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.

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()

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.

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.

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.

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()

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation