Loading...
Searching...
No Matches
Parameter Lists

## Typedefs

typedef struct _cpl_parameterlist_ | cpl_parameterlist
| The opaque parameter list data type.

## Functions

cpl_error_code | cpl_parameterlist_append (cpl_parameterlist *self, cpl_parameter *parameter)
| Append a parameter to a parameter list.
void | cpl_parameterlist_delete (cpl_parameterlist *self)
| Destroy a parameter list.
void | cpl_parameterlist_dump (const cpl_parameterlist *self, FILE *stream)
| Dump the contents of a parameter list to the given stream.
cpl_parameter * | cpl_parameterlist_find (cpl_parameterlist *self, const char *name)
| Find a parameter with the given name in a parameter list.
const cpl_parameter * | cpl_parameterlist_find_const (const cpl_parameterlist *self, const char *name)
| Find a parameter with the given name in a parameter list.
cpl_parameter * | cpl_parameterlist_find_context (cpl_parameterlist *self, const char *context)
| Find a parameter which belongs to the given context in a parameter list.
const cpl_parameter * | cpl_parameterlist_find_context_const (const cpl_parameterlist *self, const char *context)
| Find a parameter which belongs to the given context in a parameter list.
cpl_parameter * | cpl_parameterlist_find_tag (cpl_parameterlist *self, const char *tag)
| Find a parameter with the given tag in a parameter list.
const cpl_parameter * | cpl_parameterlist_find_tag_const (const cpl_parameterlist *self, const char *tag)
| Find a parameter with the given tag in a parameter list.
cpl_parameter * | cpl_parameterlist_find_type (cpl_parameterlist *self, cpl_type type)
| Find a parameter of the given type in a parameter list.
const cpl_parameter * | cpl_parameterlist_find_type_const (const cpl_parameterlist *self, cpl_type type)
| Find a parameter of the given type in a parameter list.
cpl_parameter * | cpl_parameterlist_get_first (cpl_parameterlist *self)
| Get the first parameter in the given parameter list.
const cpl_parameter * | cpl_parameterlist_get_first_const (const cpl_parameterlist *self)
| Get the first parameter in the given parameter list.
cpl_parameter * | cpl_parameterlist_get_last (cpl_parameterlist *self)
| Get the last parameter in the given list.
const cpl_parameter * | cpl_parameterlist_get_last_const (const cpl_parameterlist *self)
| Get the last parameter in the given list.
cpl_parameter * | cpl_parameterlist_get_next (cpl_parameterlist *self)
| Get the next parameter in the given list.
const cpl_parameter * | cpl_parameterlist_get_next_const (const cpl_parameterlist *self)
| Get the next parameter in the given list.
cpl_size | cpl_parameterlist_get_size (const cpl_parameterlist *self)
| Get the current size of a parameter list.
cpl_parameterlist * | cpl_parameterlist_new (void)
| Create a new parameter list.

## Detailed Description

The module implements a parameter list data type, a container for the cpl_parameter type. It provides a convenient way to pass a set of parameters, as a whole, to a function.

It is used in the plugin interface (cf. Plugin Interface), for instance, to pass the parameters a recipe accepts from the plugin to the calling application and vice versa.

All functions expect a valid pointer to a parameter list as input, unless otherwise specified.

Synopsis:
  #include <cpl_parameterlist.h>

## Typedef Documentation

## cpl_parameterlist

typedef struct _cpl_parameterlist_ cpl_parameterlist

The opaque parameter list data type.

## Function Documentation

## cpl_parameterlist_append()

cpl_error_code cpl_parameterlist_append | ( | cpl_parameterlist * | self,
|  | cpl_parameter * | parameter )

Append a parameter to a parameter list.

Parameters

  self | A parameter list.
  parameter | The parameter to append.

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 parameter parameter is appended to the parameter list self.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_parameterlist_delete()

void cpl_parameterlist_delete | ( | cpl_parameterlist * | self | ) |

Destroy a parameter list.

Parameters

  self | The parameter list to destroy.

Returns
  Nothing.

The function destroys the parameter list object self and all parameters it possibly contains. The individual parameters are destroyed using the parameter destructor (cf. Parameters). If self is `NULL`, nothing is done and no error is set.

References cpl_parameter_delete().

## cpl_parameterlist_dump()

void cpl_parameterlist_dump | ( | const cpl_parameterlist * | self,
|  | FILE * | stream )

Dump the contents of a parameter list to the given stream.

Parameters

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

Returns
  Nothing.

The function dumps the debugging information for each parameter found in the parameter list self to the output stream stream. The debugging information for each individual parameter is dumped using cpl_parameter_dump(). If self is `NULL` the function does nothing.

See also
  cpl_parameter_dump()

References cpl_parameter_dump().

## cpl_parameterlist_find()

cpl_parameter * cpl_parameterlist_find | ( | cpl_parameterlist * | self,
|  | const char * | name )

Find a parameter with the given name in a parameter list.

Parameters

  self | A parameter list.
  name | The parameter name to search for.

Returns
  The function returns a handle for the first parameter with the name name, or `NULL` if no such parameter was found. If an error occurs the function returns `NULL` and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self or name is a NULL pointer.

The function searches the parameter list self for the first occurrence of a parameter with the fully qualified name name. If no parameter with this name exists, the function returns `NULL`.

References cpl_error_set_where, cpl_errorstate_get(), cpl_errorstate_is_equal(), and cpl_parameterlist_find_const().

## cpl_parameterlist_find_const()

const cpl_parameter * cpl_parameterlist_find_const | ( | const cpl_parameterlist * | self,
|  | const char * | name )

Find a parameter with the given name in a parameter list.

Parameters

  self | A parameter list.
  name | The parameter name to search for.

Returns
  The function returns a handle for the first parameter with the name name, or `NULL` if no such parameter was found. If an error occurs the function returns `NULL` and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self or name is a NULL pointer.

The function searches the parameter list self for the first occurrence of a parameter with the fully qualified name name. If no parameter with this name exists, the function returns `NULL`.

References CPL_ERROR_NULL_INPUT, and cpl_parameter_get_name().

Referenced by cpl_parameterlist_find().

## cpl_parameterlist_find_context()

cpl_parameter * cpl_parameterlist_find_context | ( | cpl_parameterlist * | self,
|  | const char * | context )

Find a parameter which belongs to the given context in a parameter list.

Parameters

  self | A parameter list.
  context | The parameter context to search for.

Returns
  The function returns a handle for the first parameter with the context context, or `NULL` if no such parameter was found. If an error occurs the function returns `NULL` and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self or context is a NULL pointer.

The function searches the parameter list self for the first occurrence of a parameter which belongs to the context context. If no parameter with this type exists, the function returns `NULL`.

References cpl_error_set_where, cpl_errorstate_get(), cpl_errorstate_is_equal(), and cpl_parameterlist_find_context_const().

## cpl_parameterlist_find_context_const()

const cpl_parameter * cpl_parameterlist_find_context_const | ( | const cpl_parameterlist * | self,
|  | const char * | context )

Find a parameter which belongs to the given context in a parameter list.

Parameters

  self | A parameter list.
  context | The parameter context to search for.

Returns
  The function returns a handle for the first parameter with the context context, or `NULL` if no such parameter was found. If an error occurs the function returns `NULL` and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self or context is a NULL pointer.

The function searches the parameter list self for the first occurrence of a parameter which belongs to the context context. If no parameter with this type exists, the function returns `NULL`.

References CPL_ERROR_NULL_INPUT, and cpl_parameter_get_context().

Referenced by cpl_parameterlist_find_context().

## cpl_parameterlist_find_tag()

cpl_parameter * cpl_parameterlist_find_tag | ( | cpl_parameterlist * | self,
|  | const char * | tag )

Find a parameter with the given tag in a parameter list.

Parameters

  self | A parameter list.
  tag | The parameter tag to search for.

Returns
  The function returns a handle for the first parameter with the tag tag, or `NULL` if no such parameter was found. If an error occurs the function returns `NULL` and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self or tag is a NULL pointer.

The function searches the parameter list self for the first occurrence of a parameter with the user tag tag. If no parameter with this tag exists, the function returns `NULL`.

References cpl_error_set_where, cpl_errorstate_get(), cpl_errorstate_is_equal(), and cpl_parameterlist_find_tag_const().

## cpl_parameterlist_find_tag_const()

const cpl_parameter * cpl_parameterlist_find_tag_const | ( | const cpl_parameterlist * | self,
|  | const char * | tag )

Find a parameter with the given tag in a parameter list.

Parameters

  self | A parameter list.
  tag | The parameter tag to search for.

Returns
  The function returns a handle for the first parameter with the tag tag, or `NULL` if no such parameter was found. If an error occurs the function returns `NULL` and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self or tag is a NULL pointer.

The function searches the parameter list self for the first occurrence of a parameter with the user tag tag. If no parameter with this tag exists, the function returns `NULL`.

References CPL_ERROR_NULL_INPUT, and cpl_parameter_get_tag().

Referenced by cpl_parameterlist_find_tag().

## cpl_parameterlist_find_type()

cpl_parameter * cpl_parameterlist_find_type | ( | cpl_parameterlist * | self,
|  | cpl_type | type )

Find a parameter of the given type in a parameter list.

Parameters

  self | A parameter list.
  type | The parameter type to search for.

Returns
  The function returns a handle for the first parameter with the type type, or `NULL` if no such parameter was found. 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.

The function searches the parameter list self for the first occurrence of a parameter whose value is of the type type. If no parameter with this type exists, the function returns `NULL`.

References cpl_error_set_where, cpl_errorstate_get(), cpl_errorstate_is_equal(), and cpl_parameterlist_find_type_const().

## cpl_parameterlist_find_type_const()

const cpl_parameter * cpl_parameterlist_find_type_const | ( | const cpl_parameterlist * | self,
|  | cpl_type | type )

Find a parameter of the given type in a parameter list.

Parameters

  self | A parameter list.
  type | The parameter type to search for.

Returns
  The function returns a handle for the first parameter with the type type, or `NULL` if no such parameter was found. 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.

The function searches the parameter list self for the first occurrence of a parameter whose value is of the type type. If no parameter with this type exists, the function returns `NULL`.

References CPL_ERROR_NULL_INPUT, and cpl_parameter_get_type().

Referenced by cpl_parameterlist_find_type().

## cpl_parameterlist_get_first()

cpl_parameter * cpl_parameterlist_get_first | ( | cpl_parameterlist * | self | ) |

Get the first parameter in the given parameter list.

Parameters

  self | A parameter list.

Returns
  The function returns a handle for the first parameter in the list, or `NULL` if the list is empty. 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.

The function returns the first parameter in the parameter list self, if it exists. If there is no first parameter, i.e. if the list is empty, `NULL` is returned. The function updates the internal search position cache.

References cpl_error_set_where, cpl_errorstate_get(), cpl_errorstate_is_equal(), and cpl_parameterlist_get_first_const().

## cpl_parameterlist_get_first_const()

const cpl_parameter * cpl_parameterlist_get_first_const | ( | const cpl_parameterlist * | self | ) |

Get the first parameter in the given parameter list.

Parameters

  self | A parameter list.

Returns
  The function returns a handle for the first parameter in the list, or `NULL` if the list is empty. 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.

The function returns the first parameter in the parameter list self, if it exists. If there is no first parameter, i.e. if the list is empty, `NULL` is returned. The function updates the internal search position cache.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_dfs_setup_product_header(), and cpl_parameterlist_get_first().

## cpl_parameterlist_get_last()

cpl_parameter * cpl_parameterlist_get_last | ( | cpl_parameterlist * | self | ) |

Get the last parameter in the given list.

Parameters

  self | A parameter list.

Returns
  The function returns a handle for the last parameter in the list. 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 self is an empty list.

The function returns the last parameter stored in the parameter list self. The list self must not be empty.

References cpl_error_set_where, cpl_errorstate_get(), cpl_errorstate_is_equal(), and cpl_parameterlist_get_last_const().

## cpl_parameterlist_get_last_const()

const cpl_parameter * cpl_parameterlist_get_last_const | ( | const cpl_parameterlist * | self | ) |

Get the last parameter in the given list.

Parameters

  self | A parameter list.

Returns
  The function returns a handle for the last parameter in the list. 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 self is an empty list.

The function returns the last parameter stored in the parameter list self. The list self must not be empty.

References CPL_ERROR_ILLEGAL_INPUT, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_parameterlist_get_last().

## cpl_parameterlist_get_next()

cpl_parameter * cpl_parameterlist_get_next | ( | cpl_parameterlist * | self | ) |

Get the next parameter in the given list.

Parameters

  self | A parameter list.

Returns
  The function returns a handle for the next parameter in the list, or `NULL` if there are no more parameters in the list. 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.

The function returns the next parameter in the parameter list self if it exists and `NULL` otherwise. The function uses the last cached search position to determine the most recently accessed parameter. This means that the function only works as expected if the self has been initialised by a call to cpl_parameterlist_get_first(), and if no function updating the internal cache was called between two subsequent calls to this function.

References cpl_error_set_where, cpl_errorstate_get(), cpl_errorstate_is_equal(), and cpl_parameterlist_get_next_const().

## cpl_parameterlist_get_next_const()

const cpl_parameter * cpl_parameterlist_get_next_const | ( | const cpl_parameterlist * | self | ) |

Get the next parameter in the given list.

Parameters

  self | A parameter list.

Returns
  The function returns a handle for the next parameter in the list, or `NULL` if there are no more parameters in the list. 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.

The function returns the next parameter in the parameter list self if it exists and `NULL` otherwise. The function uses the last cached search position to determine the most recently accessed parameter. This means that the function only works as expected if the self has been initialised by a call to cpl_parameterlist_get_first_const(), and if no function updating the internal cache was called between two subsequent calls to this function.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_dfs_setup_product_header(), and cpl_parameterlist_get_next().

## cpl_parameterlist_get_size()

cpl_size cpl_parameterlist_get_size | ( | const cpl_parameterlist * | self | ) |

Get the current size of a parameter list.

Parameters

  self | A parameter list

Returns
  The parameter list's current size, or 0 if the list is empty. 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 reports the current number of elements stored in the parameter list self.

References CPL_ERROR_NULL_INPUT.

## cpl_parameterlist_new()

cpl_parameterlist * cpl_parameterlist_new | ( | void |  | ) |

Create a new parameter list.

Returns
  A pointer to the newly created parameter list.

The function creates a new parameter list object. The created object must be destroyed using the parameter list destructor cpl_parameterlist_delete().