Main Page   Modules   Alphabetical List   Compound List   Compound Members  

Parameters


Typedefs

typedef enum _cpl_parameter_class_ cpl_parameter_class
 The parameter class data type. More...

typedef _cpl_parameter_ cpl_parameter
 The opaque parameter data type. More...


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


Functions

cpl_parameter * cpl_parameter_value_new (const char *name, cpl_type type, const char *description, const char *context,...)
 Create a new value parameter. More...

cpl_parameter * cpl_parameter_range_new (const char *name, cpl_type type, const char *description, const char *context,...)
 Create a new range parameter. More...

cpl_parameter * cpl_parameter_enum_new (const char *name, cpl_type type, const char *description, const char *context,...)
 Create a new enumeration parameter. More...

void cpl_parameter_delete (cpl_parameter *self)
 Delete a parameter. More...

int cpl_parameter_set_bool (cpl_parameter *self, int value)
 Assign a boolean value to a parameter. More...

int cpl_parameter_set_int (cpl_parameter *self, int value)
 Assign an integer value to a parameter. More...

int cpl_parameter_set_double (cpl_parameter *self, double value)
 Assign a double value to a parameter. More...

int cpl_parameter_set_string (cpl_parameter *self, const char *value)
 Assign a string value to a parameter. More...

const char * cpl_parameter_get_name (const cpl_parameter *self)
 Get the name of a parameter. More...

const char * cpl_parameter_get_context (const cpl_parameter *self)
 Get the context of a parameter. More...

const char * cpl_parameter_get_help (const cpl_parameter *self)
 Get the description of a parameter. More...

const char * cpl_parameter_get_tag (const cpl_parameter *self)
 Get the parameter's user tag. More...

cpl_type cpl_parameter_get_type (const cpl_parameter *self)
 Get the parameter's value type. More...

cpl_parameter_class cpl_parameter_get_class (const cpl_parameter *self)
 Get the parameter's class. More...

int cpl_parameter_get_bool (const cpl_parameter *self)
 Get the value of the given boolean parameter. More...

int cpl_parameter_get_int (const cpl_parameter *self)
 Get the value of the given integer parameter. More...

double cpl_parameter_get_double (const cpl_parameter *self)
 Get the value of the given double parameter. More...

char * cpl_parameter_get_string (const cpl_parameter *self)
 Get the value of the given string parameter. More...

int cpl_parameter_preset_get_bool (const cpl_parameter *self)
 Get the default value of the given boolean parameter. More...

int cpl_parameter_preset_get_int (const cpl_parameter *self)
 Get the default value of the given integer parameter. More...

double cpl_parameter_preset_get_double (const cpl_parameter *self)
 Get the default value of the given double parameter. More...

char * cpl_parameter_preset_get_string (const cpl_parameter *self)
 Get the default value of the given string parameter. More...

int cpl_parameter_set_alias (cpl_parameter *parameter, const char *cmd, const char *env, const char *file)
 Set alias names for the given parameter. More...

int cpl_parameter_set_mode (cpl_parameter *parameter, int cflag, int eflag, int fflag)
 Enables or disables the parameter for different contexts. More...

int cpl_parameter_enum_get_size (const cpl_parameter *parameter)
 Get the number of alternatives of an enumeration parameter. More...

int cpl_parameter_enum_get_int (const cpl_parameter *parameter, int index)
 Get the possible values for an integer enumeration. More...

double cpl_parameter_enum_get_double (const cpl_parameter *parameter, int index)
 Get the possible values for a double enumeration. More...

char * cpl_parameter_enum_get_string (const cpl_parameter *parameter, int index)
 Get the possible values for a string enumeration. More...

int cpl_parameter_range_get_min_int (const cpl_parameter *parameter)
 Get the minimum value of an integer range parameter. More...

double cpl_parameter_range_get_min_double (const cpl_parameter *parameter)
 Get the minimum value of a double range parameter. More...

int cpl_parameter_range_get_max_int (const cpl_parameter *parameter)
 Get the maximum value of an integer range parameter. More...

double cpl_parameter_range_get_max_double (const cpl_parameter *parameter)
 Get the maximum value of a double range parameter. More...

int cpl_parameter_get_present (const cpl_parameter *parameter)
 Get the presence status flag of the given parameter. More...

void cpl_parameter_set_present (cpl_parameter *parameter, int status)
 Change the presence status flag of the given parameter. More...

int cpl_parameter_get_id (const cpl_parameter *parameter)
 Get the numerical identifier of the given parameter. More...

void cpl_parameter_set_id (cpl_parameter *parameter, int id)
 Set the numerical identifier of the given parameter. More...

char * cpl_parameter_get_cmdl_keyword (const cpl_parameter *parameter)
 Get the command line alias name of the given parameter. More...

void cpl_parameter_set_cmdl_keyword (cpl_parameter *parameter, char *alias)
 Set the command line alias name of the given parameter. More...

int cpl_parameter_get_cmdl_active (const cpl_parameter *parameter)
 Get the parameter's activity status for the command line context. More...

void cpl_parameter_set_cmdl_active (cpl_parameter *parameter, int active)
 Set the parameter's activity status for the command line context. More...

char * cpl_parameter_get_env_keyword (const cpl_parameter *parameter)
 Get the environment alias name of the given parameter. More...

void cpl_parameter_set_env_keyword (cpl_parameter *parameter, char *alias)
 Set the environment alias name of the given parameter. More...

int cpl_parameter_get_env_active (const cpl_parameter *parameter)
 Get the parameter's activity status for the environment context. More...

void cpl_parameter_set_env_active (cpl_parameter *parameter, int active)
 Set the parameter's activity status for the environment context. More...

char * cpl_parameter_get_file_keyword (const cpl_parameter *parameter)
 Get the configuration file alias name of the given parameter. More...

void cpl_parameter_set_file_keyword (cpl_parameter *parameter, char *alias)
 Set the configuration file alias name of the given parameter. More...

int cpl_parameter_get_file_active (const cpl_parameter *parameter)
 Get the parameter's activity status for the configuration file context. More...

void cpl_parameter_set_file_active (cpl_parameter *parameter, int active)
 Set the parameter's activity status for the configuration file context. More...

void cpl_parameter_print (const cpl_parameter *parameter)
 Prints the given parameter. More...


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:

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): 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_value_new("Value", CPL_TYPE_INT,
                                     "This is a plain value of type integer",
                                     "Example",
                                     -1);

     range = cpl_parameter_range_new("Range", CPL_TYPE_DOUBLE,
                                     "This is a value range of type double",
                                     "Example",
                                     0.5, 0.0, 1.0);

     enumeration = cpl_parameter_enum_new("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.


Enumeration Type Documentation

enum _cpl_parameter_class_
 

Supported parameter classes.

Enumeration values:
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.


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.

double cpl_parameter_enum_get_double const cpl_parameter   parameter,
int    index
 

Get the possible values for a double enumeration.

Parameters:
parameter  An enumeration parameter
index  Position to look up in the list of possible values.
Returns:
The double value at position index in the list of possible values of the enumeration parameter. In case of an error the function returns 0. and an appropriate error code is set.
The function retrieves the double value at position index from the list of enumeration values the parameter parameter can possibly take. For any valid enumeration parameter this list contains at leas one value. The possible values are counted starting from 0.

If the parameter parameter does not point to a valid parameter, but is NULL, the function returns an error and sets the error code CPL_ERROR_NULL_INPUT. If the parameter's class is not equal to CPL_PARAMETER_CLASS_ENUM, or if the parameter is not a double parameter (the parameter type is not equal to CPL_TYPE_DOUBLE), the error code CPL_ERROR_TYPE_MISMATCH is set and if the requested index position is out of range the error code is set to CPL_ERROR_ACCESS_OUT_OF_RANGE.

int cpl_parameter_enum_get_int const cpl_parameter   parameter,
int    index
 

Get the possible values for an integer enumeration.

Parameters:
parameter  An enumeration parameter
index  Position to look up in the list of possible values.
Returns:
The integer value at position index in the list of possible values of the enumeration parameter. In case of an error the function returns 0 and an appropriate error code is set.
The function retrieves the integer value at position index from the list of enumeration values the parameter parameter can possibly take. For any valid enumeration parameter this list contains at leas one value. The possible values are counted starting from 0.

If the parameter parameter does not point to a valid parameter, but is NULL, the function returns an error and sets the error code CPL_ERROR_NULL_INPUT. If the parameter's class is not equal to CPL_PARAMETER_CLASS_ENUM, or if the parameter is not an integer parameter (the parameter type is not equal to CPL_TYPE_INT), the error code CPL_ERROR_TYPE_MISMATCH is set and if the requested index position is out of range the error code is set to CPL_ERROR_ACCESS_OUT_OF_RANGE.

int cpl_parameter_enum_get_size const cpl_parameter   parameter
 

Get the number of alternatives of an enumeration parameter.

Parameters:
parameter  An enumeration parameter.
Returns:
The number of possible values the parameter parameter can take, or 0 if parameter 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.
The function retrieves the number of possible alternatives for an enumeration parameter, which is always greater or equal than 1. If parameter is NULL, or the parameter's class in not equal to CPL_PARAMETER_CLASS_ENUM the function returns an error. In the former case the error code CPL_ERROR_NULL_INPUT is set and in the latter case the error code will be CPL_ERROR_TYPE_MISMATCH.

char* cpl_parameter_enum_get_string const cpl_parameter   parameter,
int    index
 

Get the possible values for a string enumeration.

Parameters:
parameter  An enumeration parameter
index  Position to look up in the list of possible values.
Returns:
The string value at position index in the list of possible values of the enumeration parameter. In case of an error the function returns NULL and an appropriate error code is set.
The function retrieves the string value at position index from the list of enumeration values the parameter parameter can possibly take. For any valid enumeration parameter this list contains at leas one value. The possible values are counted starting from 0.

If the parameter parameter does not point to a valid parameter, but is NULL, the function returns an error and sets the error code CPL_ERROR_NULL_INPUT. If the parameter's class is not equal to CPL_PARAMETER_CLASS_ENUM, or if the parameter is not a string parameter (the parameter type is not equal to CPL_TYPE_STRING), the error code CPL_ERROR_TYPE_MISMATCH is set and if the requested index position is out of range the error code is set to CPL_ERROR_ACCESS_OUT_OF_RANGE.

cpl_parameter* cpl_parameter_enum_new 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 the error code is set to CPL_ERROR_NULL_INPUT if name is NULL or to CPL_ERROR_INVALID_TYPE if type is not supported.
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_enum_new("application.setup.enum",
                                                 CPL_TYPE_STRING,
                                                 "An enum of type string",
                                                 "application.setup",
                                                 first, 3, first, second,
                                                 third);
See also:
cpl_parameter_value_new(), cpl_parameter_range_new()

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 the parameter self is not a valid parameter, but NULL, or if the parameter is not of the correct type, the function returns 0 and an appropriate error code is set.
The current boolean 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 a boolean parameter, i.e. the parameter's type is different from CPL_TYPE_BOOL, the error code CPL_ERROR_TYPE_MISMATCH is set.

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 the error code CPL_ERROR_NULL_INPUT is also set.
The class identifier of the parameter self is retrieved.

int cpl_parameter_get_cmdl_active const cpl_parameter   parameter
 

Get the parameter's activity status for the command line context.

Parameters:
parameter  A parameter.
Returns:
A non-zero value if the parameter is enabled for the command line context, or 0 if the parameter is not active.
The function returns whether the parameter is enabled for the command line 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.

See also:
cpl_parameter_set_mode()

char* cpl_parameter_get_cmdl_keyword const cpl_parameter   parameter
 

Get the command line alias name of the given parameter.

Parameters:
parameter  A parameter.
Returns:
The function returns the parameter's context specific alias name. If no alias name was previously assigned, or if the parameter parameter does not point to a valid parameter the function returns NULL.
The function retrieves the command line alias name of the parameter parameter.

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 to which a parameter belongs, or NULL if no context has been set. The function also returns NULL if self is not a valid parameter, but NULL. In this case the error code CPL_ERROR_NULL_INPUT is also set.
The function returns the context to which the parameter self belongs. The parameter's context must not be modified using the returned pointer.

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 the parameter self is not a valid parameter, but NULL, or if the parameter is not of the correct type, the function returns 0. and an appropriate error code is set.
The current double 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 double parameter, i.e. the parameter's type is different from CPL_TYPE_DOUBLE, the error code CPL_ERROR_TYPE_MISMATCH is set.

int cpl_parameter_get_env_active const cpl_parameter   parameter
 

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

Parameters:
parameter  A parameter.
Returns:
A non-zero value if the parameter is enabled for the environment context, or 0 if the parameter is not active.
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.

See also:
cpl_parameter_set_mode()

char* cpl_parameter_get_env_keyword const cpl_parameter   parameter
 

Get the environment alias name of the given parameter.

Parameters:
parameter  A parameter.
Returns:
The function returns the parameter's context specific alias name. If no alias name was previously assigned, or if the parameter parameter does not point to a valid parameter the function returns NULL.
The function retrieves the environment alias name of the parameter parameter.

int cpl_parameter_get_file_active const cpl_parameter   parameter
 

Get the parameter's activity status for the configuration file context.

Parameters:
parameter  A parameter.
Returns:
A non-zero value if the parameter is enabled for the configuration file context, or 0 if the parameter is not active.
The function returns whether the parameter is enabled for the configuration file 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.

See also:
cpl_parameter_set_mode()

char* cpl_parameter_get_file_keyword const cpl_parameter   parameter
 

Get the configuration file alias name of the given parameter.

Parameters:
parameter  A parameter.
Returns:
The function returns the parameter's context specific alias name. If no alias name was previously assigned, or if the parameter parameter does not point to a valid parameter the function returns NULL.
The function retrieves the alias name of the parameter parameter for the configuration file context.

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 also returns NULL if self is not a valid parameter, but NULL. In this case the error code CPL_ERROR_NULL_INPUT is also set.
The function returns the 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   parameter
 

Get the numerical identifier of the given parameter.

Parameters:
parameter  A parameter.
Returns:
The function returns the parameter's numerical identifier.
The function looks up the numerical identifier of the given parameter parameter. 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 the parameter self is not a valid parameter, but NULL, or if the parameter is not of the correct type, the function returns 0 and an appropriate error code is set.
The current integer 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 integer parameter, i.e. the parameter's type is different from CPL_TYPE_INT, the error code CPL_ERROR_TYPE_MISMATCH is set.

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.
The function returns the unique name of the parameter self. The parameter name must not be modified using the returned pointer.

int cpl_parameter_get_present const cpl_parameter   parameter
 

Get the presence status flag of the given parameter.

Parameters:
parameter  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.
The function indicates whether the given parameter parameter 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 (cf. cpl_parameter_set_present()) and query it later using this function.

If the parameter parameter does not point to a valid parameter, but is NULL, the function returns 0.

See also:
cpl_parameter_set_present()

char* cpl_parameter_get_string const cpl_parameter   self
 

Get the value of the given string parameter.

Parameters:
self  An string parameter.
Returns:
The function returns the parameter's string value. If the parameter self is not a valid parameter, but NULL, or if the parameter is not of the correct type, the function returns NULL and an appropriate error code is set.
The current string 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_STRING, the error code CPL_ERROR_TYPE_MISMATCH is set.

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 also returns NULL if self is not a valid parameter, but NULL. In this case the error code CPL_ERROR_NULL_INPUT is also set.
The current 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 the error code CPL_ERROR_NULL_INPUT is also set.
The type identifier of the parameter's value is retrieved from the given parameter self.

int cpl_parameter_preset_get_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 boolean default value. TRUE is represented as non-zero value; whereas 0 indicates FALSE. If the parameter self is not a valid parameter, but NULL, or if the parameter is not of the correct type, the function returns 0 and an appropriate error code is set.
The current boolean 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 a boolean parameter, i.e. the parameter's type is different from CPL_TYPE_BOOL, the error code CPL_ERROR_TYPE_MISMATCH is set.

double cpl_parameter_preset_get_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 double default value. If the parameter self is not a valid parameter, but NULL, or if the parameter is not of the correct type, the function returns 0. and an appropriate error code is set.
The current double 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 double parameter, i.e. the parameter's type is different from CPL_TYPE_INT, the error code CPL_ERROR_TYPE_MISMATCH is set.

int cpl_parameter_preset_get_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 integer default value. If the parameter self is not a valid parameter, but NULL, or if the parameter is not of the correct type, the function returns 0 and an appropriate error code is set.
The current integer 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 integer parameter, i.e. the parameter's type is different from CPL_TYPE_INT, the error code CPL_ERROR_TYPE_MISMATCH is set.

char* cpl_parameter_preset_get_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 string default value. If the parameter self is not a valid parameter, but NULL, or if the parameter is not of the correct type, the function returns NULL and an appropriate error code is set.
The current 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.

void cpl_parameter_print const cpl_parameter   parameter
 

Prints the given parameter.

Parameters:
parameter  A parameter.
Returns:
Nothing.
The function prints the current values of all data members of the parameter parameter. The output is written using the currently installed log handler (by default the output is written to the standard output).

Note:
This function is only provided for debugging purposes.

double cpl_parameter_range_get_max_double const cpl_parameter   parameter
 

Get the maximum value of a double range parameter.

Parameters:
parameter  A double range parameter.
Returns:
The function returns the maximum double value the range parameter parameter can take. In case of an error, the function returns 0. and sets an appropriate error code.
The function retrieves the double value defined to be the upper limit of the double range parameter parameter.

If the parameter parameter does not point to a valid parameter, but is NULL, the function sets the error code CPL_ERROR_NULL_INPUT. If the parameter's class is not equal to CPL_PARAMETER_CLASS_RANGE, or if the parameter's type is not equal to CPL_TYPE_DOUBLE the error code CPL_ERROR_TYPE_MISMATCH is set.

int cpl_parameter_range_get_max_int const cpl_parameter   parameter
 

Get the maximum value of an integer range parameter.

Parameters:
parameter  An integer range parameter.
Returns:
The function returns the maximum integer value the range parameter parameter can take. In case of an error, the function returns 0 and sets an appropriate error code.
The function retrieves the integer value defined to be the upper limit of the integer range parameter parameter.

If the parameter parameter does not point to a valid parameter, but is NULL, the function sets the error code CPL_ERROR_NULL_INPUT. If the parameter's class is not equal to CPL_PARAMETER_CLASS_RANGE, or if the parameter's type is not equal to CPL_TYPE_INT the error code CPL_ERROR_TYPE_MISMATCH is set.

double cpl_parameter_range_get_min_double const cpl_parameter   parameter
 

Get the minimum value of a double range parameter.

Parameters:
parameter  A double range parameter.
Returns:
The function returns the minimum double value the range parameter parameter can take. In case of an error, the function returns 0. and sets an appropriate error code.
The function retrieves the double value defined to be the lower limit of the double range parameter parameter.

If the parameter parameter does not point to a valid parameter, but is NULL, the function sets the error code CPL_ERROR_NULL_INPUT. If the parameter's class is not equal to CPL_PARAMETER_CLASS_RANGE, or if the parameter's type is not equal to CPL_TYPE_DOUBLE the error code CPL_ERROR_TYPE_MISMATCH is set.

int cpl_parameter_range_get_min_int const cpl_parameter   parameter
 

Get the minimum value of an integer range parameter.

Parameters:
parameter  An integer range parameter.
Returns:
The function returns the minimum integer value the range parameter parameter can take. In case of an error, the function returns 0 and sets an appropriate error code.
The function retrieves the integer value defined to be the lower limit of the integer range parameter parameter.

If the parameter parameter does not point to a valid parameter, but is NULL, the function sets the error code CPL_ERROR_NULL_INPUT. If the parameter's class is not equal to CPL_PARAMETER_CLASS_RANGE, or if the parameter's type is not equal to CPL_TYPE_INT the error code CPL_ERROR_TYPE_MISMATCH is set.

cpl_parameter* cpl_parameter_range_new 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 the error code is set to CPL_ERROR_NULL_INPUT if name is NULL or to CPL_ERROR_INVALID_TYPE if type is not supported.
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_range_new("application.setup.range",
                                                 CPL_TYPE_DOUBLE,
                                                 "A range of type double",
                                                 "application.setup",
                                                 def, min, max);
See also:
cpl_parameter_value_new(), cpl_parameter_enum_new()

int cpl_parameter_set_alias cpl_parameter   parameter,
const char *    cmd,
const char *    env,
const char *    file
 

Set alias names for the given parameter.

Parameters:
parameter  A parameter
cmd  The command line alias name.
env  The environment variable alias name.
file  The alias name for configuration files.
Returns:
The function returns 0 if the alias names were set successfully, or 1 if an error occurred. If parameter is not pointing to a valid parameter the function returns also 1.
The function assigns alternative names to the parameter parameter. These alias names may be used instead of the fully qualified parameter name in the context for which they have been set. If no alias name should be assigned for any of the three contexts (command line, environment variable and configuration file) the respective argument, cmd, env, or file must be set to NULL.

int 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 0 if the value was successfully assigned, or 1 if an error occurred. In the latter case the error code CPL_ERROR_NULL_INPUT is set if self did not point to a valid parameter and CPL_ERROR_TYPE_MISMATCH if self's type is not 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.

void cpl_parameter_set_cmdl_active cpl_parameter   parameter,
int    active
 

Set the parameter's activity status for the command line context.

Parameters:
parameter  A parameter.
active  Activity flag.
Returns:
Nothing.
The function assigns the activity status passed as active to the given parameter parameter. A non-zero activity status enables the parameter for the command line context and a activity status equal to 0 disables it.

See also:
cpl_parameter_set_mode()

void cpl_parameter_set_cmdl_keyword cpl_parameter   parameter,
char *    alias
 

Set the command line alias name of the given parameter.

Parameters:
parameter  A parameter.
alias  Alias name to assign.
Returns:
Nothing.
The function defines alias as the parameter's alias name for the command line context. If a NULL pointer is passed instead of a valid parameter the function returns immediately.

See also:
cpl_parameter_set_alias()

int 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 0 if the value was successfully assigned, or 1 if an error occurred. In the latter case the error code CPL_ERROR_NULL_INPUT is set if self did not point to a valid parameter and CPL_ERROR_TYPE_MISMATCH if self's type is not CPL_TYPE_DOUBLE.
The function assigns a double value value to a parameter of type CPL_TYPE_DOUBLE.

void cpl_parameter_set_env_active cpl_parameter   parameter,
int    active
 

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

Parameters:
parameter  A parameter.
active  Activity flag.
Returns:
Nothing.
The function assigns the activity status passed as active to the given parameter parameter. A non-zero activity status enables the parameter for the environment context and a activity status equal to 0 disables it.

See also:
cpl_parameter_set_mode()

void cpl_parameter_set_env_keyword cpl_parameter   parameter,
char *    alias
 

Set the environment alias name of the given parameter.

Parameters:
parameter  A parameter.
alias  Alias name to assign.
Returns:
Nothing.
The function defines alias as the parameter's alias name for the environment context. If a NULL pointer is passed instead of a valid parameter the function returns immediately.

See also:
cpl_parameter_set_alias()

void cpl_parameter_set_file_active cpl_parameter   parameter,
int    active
 

Set the parameter's activity status for the configuration file context.

Parameters:
parameter  A parameter.
active  Activity flag.
Returns:
Nothing.
The function assigns the activity status passed as active to the given parameter parameter. A non-zero activity status enables the parameter for the configuration file context and a activity status equal to 0 disables it.

See also:
cpl_parameter_set_mode()

void cpl_parameter_set_file_keyword cpl_parameter   parameter,
char *    alias
 

Set the configuration file alias name of the given parameter.

Parameters:
parameter  A parameter.
alias  Alias name to assign.
Returns:
Nothing.
The function defines alias as the parameter's alias name for the configuration file context. If a NULL pointer is passed instead of a valid parameter the function returns immediately.

See also:
cpl_parameter_set_alias()

void cpl_parameter_set_id cpl_parameter   parameter,
int    id
 

Set the numerical identifier of the given parameter.

Parameters:
parameter  A parameter.
id  Numerical identifier to assign.
Returns:
Nothing.
The function assigns a numerical identifier to the parameter parameter. 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()

int 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 0 if the value was successfully assigned, or 1 if an error occurred. In the latter case the error code CPL_ERROR_NULL_INPUT is set if self did not point to a valid parameter and CPL_ERROR_TYPE_MISMATCH if self's type is not CPL_TYPE_INT.
The function assigns an integer value value to a parameter of type CPL_TYPE_INT.

int cpl_parameter_set_mode cpl_parameter   parameter,
int    cflag,
int    eflag,
int    fflag
 

Enables or disables the parameter for different contexts.

Parameters:
parameter  A parameter.
cflag  Command line flag.
eflag  Environment flag.
fflag  Configuration file flag.
Returns:
The function returns 0 on success, or 1 otherwise. If parameter is not pointing to a valid parameter the function also returns 1.
This function enables or disables the given parameter parameter for the contexts command line, environment and configuration file, depending on the value passed for the arguments cflag, eflag and fflag respectively. Passing a non-zero value for any of the flags enables the parameter for the respective context, while passing 0 disables it.

If a parameter is enabled for a particular context an application may modify the parameters value if it (its fully qualified name or its context specific alias name) appears in the context. If a parameter is disabled, an application must not change the parameters value.

When a parameter is created it is enabled for all three contexts.

void cpl_parameter_set_present cpl_parameter   parameter,
int    status
 

Change the presence status flag of the given parameter.

Parameters:
parameter  A parameter.
status  The presence status value to assign.
Returns:
Nothing.
The function sets the presence status flag of the given parameter parameter 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_present()

int 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 0 if the value was successfully assigned, or 1 if an error occurred. In the latter case the error code CPL_ERROR_NULL_INPUT is set if self did not point to a valid parameter and CPL_ERROR_TYPE_MISMATCH if self's type is not CPL_TYPE_STRING.
The function assigns a string value value to a parameter of type CPL_TYPE_STRING.

cpl_parameter* cpl_parameter_value_new 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 the error code is set to CPL_ERROR_NULL_INPUT if name is NULL or to CPL_ERROR_INVALID_TYPE if type is not supported.
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_value_new("application.setup.value",
                                                 CPL_TYPE_INT,
                                                 "A integer value",
                                                 "application.setup",
                                                 def);
See also:
cpl_parameter_range_new(), cpl_parameter_enum_new()


Generated on Mon May 24 14:58:06 2004 for Common Pipeline Library Reference Manual by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002