Loading...
Searching...
No Matches
Recipe Configurations

## Functions

void | cpl_recipeconfig_clear (cpl_recipeconfig *self)
| Clear a recipe configuration object.
void | cpl_recipeconfig_delete (cpl_recipeconfig *self)
| Delete a recipe configuration object.
char ** | cpl_recipeconfig_get_inputs (const cpl_recipeconfig *self, const char *tag)
| Get the input configuration for a given tag.
cpl_size | cpl_recipeconfig_get_max_count (const cpl_recipeconfig *self, const char *tag, const char *input)
| Get the maximum number of frames for the given configuration and tag.
cpl_size | cpl_recipeconfig_get_min_count (const cpl_recipeconfig *self, const char *tag, const char *input)
| Get the minimum number of frames for the given configuration and tag.
char ** | cpl_recipeconfig_get_outputs (const cpl_recipeconfig *self, const char *tag)
| Get the output configuration for a given tag.
char ** | cpl_recipeconfig_get_tags (const cpl_recipeconfig *self)
| Get the list of supported configuration tags.
int | cpl_recipeconfig_is_required (const cpl_recipeconfig *self, const char *tag, const char *input)
| Check whether a frame with the given tag is required.
cpl_recipeconfig * | cpl_recipeconfig_new (void)
| Create a new recipe configuration object.
int | cpl_recipeconfig_set_input (cpl_recipeconfig *self, const char *tag, const char *input, cpl_size min_count, cpl_size max_count)
| Add the configuration for the given input and configuration tag.
int | cpl_recipeconfig_set_inputs (cpl_recipeconfig *self, const char *tag, const cpl_framedata *data)
| Set the input configuration for a given tag.
int | cpl_recipeconfig_set_output (cpl_recipeconfig *self, const char *tag, const char *output)
| Add an output frame tag for the given configuration tag.
int | cpl_recipeconfig_set_outputs (cpl_recipeconfig *self, const char *tag, const char **data)
| Set the output configuration for a given tag.
int | cpl_recipeconfig_set_tag (cpl_recipeconfig *self, const char *tag, cpl_size min_count, cpl_size max_count)
| Set a configuration tag.
int | cpl_recipeconfig_set_tags (cpl_recipeconfig *self, const cpl_framedata *data)
| Set the list of configuration tags.

## Detailed Description

This module implements the support for recipe configurations. A recipe configuration stores information about the input data frames a recipe can process, which other input frame are needed in addition, and which output frames may be created by the recipe.

For each input frame extra information, for instance, whether a particular frame type is a required or optional recipe input, or how many frames of a certain type are at least needed, can also be stored.

The information for the individual recipe configurations and also for the individual frames can be accessed by means of a unique string identifier for the configuration and the frame respectively. This string identifier is called configuration tag in the former, and frame tag in the latter case. In particular, the configuration tag is a frame tag too, namely the frame tag of the recipe's "primary" input, or trigger frame.

The recipe configuration object stores a separate configuration for each of the different frame types, indicated by its tag, it is able to process. Each of these configurations can be retrieved, using the appropriate configuration tag as a key.

In the same way the information about individual frames can be retrieved from the selected configuration.

Synopsis:
  #include <cpl_recipeconfig.h>

## Function Documentation

## cpl_recipeconfig_clear()

void cpl_recipeconfig_clear | ( | cpl_recipeconfig * | self | ) |

Clear a recipe configuration object.

Parameters

  self | The recipe configuration object.

Returns
  Nothing.

The function clears the contents of the recipe configuration self. After the return from this call, self is empty.

See also
  cpl_recipeconfig_new()

## cpl_recipeconfig_delete()

void cpl_recipeconfig_delete | ( | cpl_recipeconfig * | self | ) |

Delete a recipe configuration object.

Parameters

  self | The recipe configuration object.

Returns
  Nothing.

The function destroys the recipe configuration object self. Any resources used by self are released. If self is `NULL`, nothing is done and no error is set.

## cpl_recipeconfig_get_inputs()

char ** cpl_recipeconfig_get_inputs | ( | const cpl_recipeconfig * | self,
|  | const char * | tag )

Get the input configuration for a given tag.

Parameters

  self | The recipe configuration object.
  tag | The tag for which the input configuration is requested.

Returns
  On success, the function returns a `NULL` terminated array of strings, and `NULL` if an error occurred. In the latter case an appropriate error code is also set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self or tag is a NULL pointer.
  CPL_ERROR_DATA_NOT_FOUND | The configuration tag tag was not found.

The function retrieves the list of input frame tags stored in the recipe configuration for the configuration tag tag from the configuration object self.

In case the input configuration for the tag tag is empty, i.e. no input frame tag has been added the function still returns a C string array. In this case the first element is set to `NULL`.

The returned array and each of its elements must be deallocated using cpl_free() if they are no longer used. The array is `NULL` terminated, i.e. the last element of the array is set to `NULL`.

References CPL_ERROR_DATA_NOT_FOUND, and CPL_ERROR_NULL_INPUT.

## cpl_recipeconfig_get_max_count()

cpl_size cpl_recipeconfig_get_max_count | ( | const cpl_recipeconfig * | self,
|  | const char * | tag,
|  | const char * | input )

Get the maximum number of frames for the given configuration and tag.

Parameters

  self | The recipe configuration object.
  tag | The configuration tag to look up.
  input | The frame tag to search for.

Returns
  The function returns the maximum number of frames with the tag input, or `-1`, if an error occurred. In the latter case an appropriate error code is set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self, tag or input is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | The configuration tag tag is NULL, or an invalid string, the empty string for instance.
  CPL_ERROR_DATA_NOT_FOUND | No frame tag tag or input was found, or self was not properly initialized.

The function queries the recipe configuration self for the configuration tag tag, searches this configuration for the frame tag input and returns the maximum number of frames required for this frame type.

If the same string is passed as tag and input, the settings for the frame with tag tag are returned.

References CPL_ERROR_DATA_NOT_FOUND, and CPL_ERROR_NULL_INPUT.

## cpl_recipeconfig_get_min_count()

cpl_size cpl_recipeconfig_get_min_count | ( | const cpl_recipeconfig * | self,
|  | const char * | tag,
|  | const char * | input )

Get the minimum number of frames for the given configuration and tag.

Parameters

  self | The recipe configuration object.
  tag | The configuration tag to look up.
  input | The frame tag to search for.

Returns
  The function returns the minimum number of frames with the tag input, or `-1`, if an error occurred. In the latter case an appropriate error code is set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self, tag or input is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | The configuration tag tag is NULL, or an invalid string, the empty string for instance.
  CPL_ERROR_DATA_NOT_FOUND | No frame tag tag or input was found, or self was not properly initialized.

The function queries the recipe configuration self for the configuration tag tag, searches this configuration for the frame tag input and returns the minimum number of frames required for this frame type.

If the same string is passed as tag and input, the settings for the frame with tag tag are returned.

References CPL_ERROR_DATA_NOT_FOUND, and CPL_ERROR_NULL_INPUT.

## cpl_recipeconfig_get_outputs()

char ** cpl_recipeconfig_get_outputs | ( | const cpl_recipeconfig * | self,
|  | const char * | tag )

Get the output configuration for a given tag.

Parameters

  self | The recipe configuration object.
  tag | The tag for which the ouput configuration is requested.

Returns
  On success, the function returns a `NULL` terminated array of strings, and `NULL` if an error occurred. In the latter case an appropriate error code is also set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self or tag is a NULL pointer.
  CPL_ERROR_DATA_NOT_FOUND | The configuration tag tag was not found.

The function retrieves the list of all possible output frame tags stored in the recipe configuration object self for the configuration tag tag.

In case the output configuration for the tag tag is empty, i.e. no output frame tag has been added the function still returns a C string array. In this case the first element is set to `NULL`.

The returned array and each of its elements must be deallocated using cpl_free() if they are no longer used. The array is `NULL` terminated, i.e. the last element of the array is set to `NULL`.

References CPL_ERROR_DATA_NOT_FOUND, and CPL_ERROR_NULL_INPUT.

## cpl_recipeconfig_get_tags()

char ** cpl_recipeconfig_get_tags | ( | const cpl_recipeconfig * | self | ) |

Get the list of supported configuration tags.

Parameters

  self | The recipe configuration object.

Returns
  On success, the function returns a `NULL` terminated array of strings, and `NULL` if an error occurred. In the latter case an appropriate error code is also set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

The function retrieves the list of configuration tags stored in the recipe configuration object self. The frame tags are returned as the elements of an array of C strings. The last element of the array is a `NULL` pointer indicating the end of the list.

In case the recipe configuration object is empty, i.e. no configuration tag has been added, or cpl_recipeconfig_clear() has been called for this object, the function still returns the C string array. In this case the first element is set to `NULL`.

If the returned list is not used any more each element, and the array itself must be deallocated using cpl_free().

References CPL_ERROR_NULL_INPUT.

## cpl_recipeconfig_is_required()

int cpl_recipeconfig_is_required | ( | const cpl_recipeconfig * | self,
|  | const char * | tag,
|  | const char * | input )

Check whether a frame with the given tag is required.

Parameters

  self | A recipe configuration object.
  tag | The configuration tag to look up.
  input | The frame tag to search for.

Returns
  The function returns `1` if the frame with the tag input is required, and `0` if the frame is not a required input. If an error occurred `-1` is returned and an appropriate error code is set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self, tag or input is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | The frame tag tag is NULL, an invalid string, the empty string for instance.
  CPL_ERROR_DATA_NOT_FOUND | No frame tag tag or input was found, or self was not properly initialized.

The function queries the recipe configuration self for the configuration tag tag and searches this configuration for the frame tag input. It returns `1` if one or more frames of type input are a mandatory input for the recipe configuration selected by tag.

If the same string is passed as tag and input, the settings for the frame with tag tag are returned.

References CPL_ERROR_DATA_NOT_FOUND, and CPL_ERROR_NULL_INPUT.

## cpl_recipeconfig_new()

cpl_recipeconfig * cpl_recipeconfig_new | ( | void |  | ) |

Create a new recipe configuration object.

Returns
  The function returns a pointer to the newly created recipe configuration.

The function creates a new, empty recipe configuration object.

## cpl_recipeconfig_set_input()

int cpl_recipeconfig_set_input | ( | cpl_recipeconfig * | self,
|  | const char * | tag,
|  | const char * | input,
|  | cpl_size | min_count,
|  | cpl_size | max_count )

Add the configuration for the given input and configuration tag.

Parameters

  self | The recipe configuration object.
  tag | The configuration tag.
  input | The input frame tag.
  min_count | The value to set as the minimum number of frames.
  max_count | The value to set as the maximum number of frames.

Returns
  The function returns `0` on success and a non-zero value if an error occurred. The return value is `-1` if self, tag or input is `NULL`, or, if tag or input is an invalid string. The function returns `1` if self was not properly initialized using cpl_recipeconfig_set_tag() or cpl_recipeconfig_set_tags(). If no tag tag is found in self the function returns `2`. If an error occurs an appropriate error code is also set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self, tag or input is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | The frame tag tag or input is an empty string, or tag and input are equal.
  CPL_ERROR_DATA_NOT_FOUND | No configuration for the tag tag was found, or self was not properly initialized.

The function sets the configuration for the input frame tag input of the configuration associated with the tag tag in the recipe configuration object self. The minimum and maximum number of frames of this input frame tag are given using the min_count and max_count arguments. Using a value of `-1` for the minimum and maximum number of frames, means that these two numbers are unspecified. Using a minimum number min_count greater then `0` makes the frame a required input.

Before an input configuration can be set using this function, the configuration tag tag must have been added to self previously using cpl_recipeconfig_set_tag() or cpl_recipeconfig_set_tags().

See also
  cpl_recipeconfig_set_tag(), cpl_recipeconfig_set_tags()

References CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_framedata_create(), and cpl_framedata_delete().

## cpl_recipeconfig_set_inputs()

int cpl_recipeconfig_set_inputs | ( | cpl_recipeconfig * | self,
|  | const char * | tag,
|  | const cpl_framedata * | data )

Set the input configuration for a given tag.

Parameters

  self | The recipe configuration object.
  tag | The tag for which the input configuration is set.
  data | An array containing the configuration informations.

Returns
  The function returns `0` on success, or a non-zero value otherwise. If self or tag is `NULL`, or if tag is invalid, i.e. the empty string the function returns `-1` and sets an appropriate error code. If no configuration tags were previously configured using cpl_recipeconfig_set_tag() or cpl_recipeconfig_set_tags() the function returns `1`. If no configuration was found for the given tag tag the return value is `2`. Finally, if the frame tag to add to the configuration is invalid, the function returns `3`.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self or tag is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | The frame tag tag is an invalid tag, i.e. the empty string or the input frame tag read from data is invalid, or the same as tag.
  CPL_ERROR_DATA_NOT_FOUND | No configuration for the tag tag was found, or self was not properly initialized.

The function sets the input configuration for the tag tag in the recipe configuration object self. The minimum and maximum number of frames of this tag can be given using the arguments min_count and max_count. Using a value of `-1` for the minimum and maximum number of frames, means that these two numbers are unspecified. Using a value greater than `0` for the minimum number of frames makes the input frame a required frame.

The function sets the configuration data for each input tag specified in the array data, until a tag set to `NULL` is reached. The array data must contain such an entry as last element, in order to indicate the end of the array.

Before an input configuration can be set using this function, the configuration tag tag must have been added to self previously using cpl_recipeconfig_set_tag() or cpl_recipeconfig_set_tags().

See also
  cpl_recipeconfig_set_tag(), cpl_recipeconfig_set_tags()

References CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_framedata_delete(), and cpl_framedata_duplicate().

## cpl_recipeconfig_set_output()

int cpl_recipeconfig_set_output | ( | cpl_recipeconfig * | self,
|  | const char * | tag,
|  | const char * | output )

Add an output frame tag for the given configuration tag.

Parameters

  self | The recipe configuration object.
  tag | The configuration tag.
  output | The output frame tag to add.

Returns
  The function returns `0` on success and a non-zero value if an error occurred. The return value is `-1` if self, tag or output is `NULL`, or if tag or input is an invalid string. The function returns `1` if self was not properly initialized using cpl_recipeconfig_set_tag() or cpl_recipeconfig_set_tags(). If no tag tag is found in self the function returns `2`. If an error occurs an appropriate error code is also set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self, tag or output is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | The frame tag tag or input is an invalid string, i.e. the empty string.
  CPL_ERROR_DATA_NOT_FOUND | No configuration for the tag tag was found, or self was not properly initialized.

The function adds the output frame tag ouput to the configuration associated with the tag tag in the recipe configuration object self.

Before an output frame tag can be set using this function, the configuration tag tag must have been added to self previously, using cpl_recipeconfig_set_tag() or cpl_recipeconfig_set_tags().

See also
  cpl_recipeconfig_set_tag(), cpl_recipeconfig_set_tags()

References CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_framedata_create(), and cpl_framedata_delete().

## cpl_recipeconfig_set_outputs()

int cpl_recipeconfig_set_outputs | ( | cpl_recipeconfig * | self,
|  | const char * | tag,
|  | const char ** | data )

Set the output configuration for a given tag.

Parameters

  self | The recipe configuration object.
  tag | The tag for which the output configuration is set.
  data | An array of strings containing the output frame tags to set.

Returns
  The function returns `0` on success, or a non-zero value otherwise. If self or tag is `NULL`, or if tag is invalid, i.e. the empty string the function returns `-1` and sets an appropriate error code. If no configuration tags were previously configured using cpl_recipeconfig_set_tag() or cpl_recipeconfig_set_tags() the function returns `1`. If no configuration was found for the given tag tag the return value is `2`.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self or tag is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | The frame tag tag is an invalid tag, i.e. the empty string.
  CPL_ERROR_DATA_NOT_FOUND | No configuration for the tag tag was found, or self was not properly initialized.

The function sets the output configuration for the tag tag in the recipe configuration object self. The output configuration is a list of all possible frame tags which could result from the execution of the corresponding recipe.

The function stores each output frame tag found in the array data, until an array element set to `NULL` is reached. The array data must contain such an entry as last element, in order to indicate the end of the array.

Before an output configuration can be set using this function, the configuration tag tag must have been added to self previously using cpl_recipeconfig_set_tag() or cpl_recipeconfig_set_tags().

See also
  cpl_recipeconfig_set_tag(), cpl_recipeconfig_set_tags()

References CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and cpl_framedata_create().

## cpl_recipeconfig_set_tag()

int cpl_recipeconfig_set_tag | ( | cpl_recipeconfig * | self,
|  | const char * | tag,
|  | cpl_size | min_count,
|  | cpl_size | max_count )

Set a configuration tag.

Parameters

  self | The recipe configuration object.
  tag | The configuration tag.
  min_count | The value to set as the minimum number of frames.
  max_count | The value to set as the maximum number of frames.

Returns
  The function returns `0` on success and a non-zero value if an error occurred. The return value is `-1` if self or tag is `NULL`, or if tag is an invalid string. If an error occurs an appropriate error code is set.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self or tag is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | The frame tag tag is an invalid tag, i.e. the empty string.

The function creates a configuration for the configuration tag tag and adds it to the recipe configuration object self. The minimum and maximum number of frames of this tag can be given using the arguments min_count and max_count. Using a value of `-1` for the minimum and maximum number of frames, means that these two numbers are unspecified. If the minimum number of frames is greater than `0`, the frame is considered to be required, otherwise it is optional.

References CPL_ERROR_ILLEGAL_INPUT, and CPL_ERROR_NULL_INPUT.

## cpl_recipeconfig_set_tags()

int cpl_recipeconfig_set_tags | ( | cpl_recipeconfig * | self,
|  | const cpl_framedata * | data )

Set the list of configuration tags.

Parameters

  self | The recipe configuration object.
  data | A frame data array from which the tags are set.

Returns
  The function returns `0` on success, or a non-zero value otherwise. Inparticular, if the self is `NULL` the function returns `-1` and sets the appropriate error code. If any configuration tag in the input array data is invalid, an empty string for instance, the function returns `1` and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | The frame data array data contains an invalid tag.

The function is a convenience function to allow an initialization of a recipe configuration from static data. The configuration tags to be stored are taken from the frame data array data and are added to the recipe configuration self. The configuration tag is copied to self.

In addition the tags can be configured using the remaining members of the frame data structures of data.

The function adds each configuration tag found in the array data to the configuration self, until a configuration tag set to NULL is reached. The array data must be terminated by such an entry, which indicates the end of the array.

References CPL_ERROR_ILLEGAL_INPUT, and CPL_ERROR_NULL_INPUT.