vars

The vars data type contains all the information about a print job, this includes information such as the printer model, paper size, print resolution etc. More...

## Data Structures

struct | stp_raw_t
| Raw parameter. More...
struct | stp_double_bound_t
| double_bound (range) parameter. More...
struct | stp_int_bound_t
| int_bound (range) parameter. More...
struct | stp_dimension_bound_t
| dimension_bound (range) parameter. More...
struct | stp_parameter_t
| Parameter description. More...

## Macros

#define | STP_RAW(x) { sizeof((x)), (x) }
#define | STP_RAW_STRING(x) { sizeof((x)) - 1, (x) }
#define | STP_CHANNEL_NONE ((unsigned char) -1)

## Typedefs

typedef struct stp_vars | stp_vars_t
| The vars opaque data type. More...
typedef void * | stp_parameter_list_t
| The parameter_list opaque data type. More...
typedef const void * | stp_const_parameter_list_t
| The constant parameter_list opaque data type. More...
typedef void(* | stp_outfunc_t) (void *data, const char *buffer, size_t bytes)
| Output function supplied by the calling application. More...
typedef void *(* | stp_copy_data_func_t) (void *)
typedef void(* | stp_free_data_func_t) (void *)
typedef struct stp_compdata | compdata_t

## Enumerations

enum | stp_parameter_type_t { STP_PARAMETER_TYPE_STRING_LIST , STP_PARAMETER_TYPE_INT , STP_PARAMETER_TYPE_BOOLEAN , STP_PARAMETER_TYPE_DOUBLE , STP_PARAMETER_TYPE_CURVE , STP_PARAMETER_TYPE_FILE , STP_PARAMETER_TYPE_RAW , STP_PARAMETER_TYPE_ARRAY , STP_PARAMETER_TYPE_DIMENSION , STP_PARAMETER_TYPE_INVALID }
| Parameter types. More...
enum | stp_parameter_class_t { STP_PARAMETER_CLASS_FEATURE , STP_PARAMETER_CLASS_OUTPUT , STP_PARAMETER_CLASS_CORE , STP_PARAMETER_CLASS_INVALID }
| Parameter class. More...
enum | stp_parameter_level_t { STP_PARAMETER_LEVEL_BASIC , STP_PARAMETER_LEVEL_ADVANCED , STP_PARAMETER_LEVEL_ADVANCED1 , STP_PARAMETER_LEVEL_ADVANCED2 , STP_PARAMETER_LEVEL_ADVANCED3 , STP_PARAMETER_LEVEL_ADVANCED4 , STP_PARAMETER_LEVEL_INTERNAL , STP_PARAMETER_LEVEL_EXTERNAL , STP_PARAMETER_LEVEL_INVALID }
| Parameter level. More...
enum | stp_parameter_activity_t { STP_PARAMETER_INACTIVE , STP_PARAMETER_DEFAULTED , STP_PARAMETER_ACTIVE }
| Parameter activity. More...
enum | stp_parameter_verify_t { PARAMETER_BAD , PARAMETER_OK , PARAMETER_INACTIVE }

## Functions

void | stp_vars_print_error (const stp_vars_t *v, const char *prefix)
| Print an stp_vars_t in debugging format. More...
stp_vars_t * | stp_vars_create (void)
| Create a new vars object. More...
void | stp_vars_copy (stp_vars_t *dest, const stp_vars_t *source)
| Copy a vars object. More...
stp_vars_t * | stp_vars_create_copy (const stp_vars_t *source)
| Copy and allocate a vars object. More...
void | stp_vars_destroy (stp_vars_t *v)
| Destroy a vars object. More...
void | stp_set_driver (stp_vars_t *v, const char *val)
| Set the name of the printer driver. More...
void | stp_set_driver_n (stp_vars_t *v, const char *val, int bytes)
| Set the name of the printer driver. More...
const char * | stp_get_driver (const stp_vars_t *v)
| Get the name of the printer driver. More...
void | stp_set_color_conversion (stp_vars_t *v, const char *val)
| Set the name of the color conversion routine, if not the default. More...
void | stp_set_color_conversion_n (stp_vars_t *v, const char *val, int bytes)
| Set the name of the color conversion routine, if not the default. More...
const char * | stp_get_color_conversion (const stp_vars_t *v)
| Get the name of the color conversion routine. More...
void | stp_set_left (stp_vars_t *v, stp_dimension_t val)
| Set the left edge of the image. More...
stp_dimension_t | stp_get_left (const stp_vars_t *v)
| Get the left edge of the image. More...
void | stp_set_top (stp_vars_t *v, stp_dimension_t val)
| Set the top edge of the image. More...
stp_dimension_t | stp_get_top (const stp_vars_t *v)
| Get the top edge of the image. More...
void | stp_set_width (stp_vars_t *v, stp_dimension_t val)
| Set the width of the image. More...
stp_dimension_t | stp_get_width (const stp_vars_t *v)
| Get the width edge of the image. More...
void | stp_set_height (stp_vars_t *v, stp_dimension_t val)
| Set the height of the image. More...
stp_dimension_t | stp_get_height (const stp_vars_t *v)
| Get the height of the image. More...
void | stp_set_page_width (stp_vars_t *v, stp_dimension_t val)
| Set the page width. More...
stp_dimension_t | stp_get_page_width (const stp_vars_t *v)
| Get the page width. More...
void | stp_set_page_height (stp_vars_t *v, stp_dimension_t val)
| Set the page height. More...
stp_dimension_t | stp_get_page_height (const stp_vars_t *v)
| Get the page height. More...
void | stp_set_outfunc (stp_vars_t *v, stp_outfunc_t val)
| Set the function used to print output information. More...
stp_outfunc_t | stp_get_outfunc (const stp_vars_t *v)
| Get the function used to print output information. More...
void | stp_set_errfunc (stp_vars_t *v, stp_outfunc_t val)
| Set the function used to print error information. More...
stp_outfunc_t | stp_get_errfunc (const stp_vars_t *v)
| Get the function used to print output information. More...
void | stp_set_dbgfunc (stp_vars_t *v, stp_outfunc_t val)
| Set the function used to print diagnostic information. More...
stp_outfunc_t | stp_get_dbgfunc (const stp_vars_t *v)
| Get the function used to print output information. More...
void | stp_set_outdata (stp_vars_t *v, void *val)
| Set the output data. More...
void * | stp_get_outdata (const stp_vars_t *v)
| Get the output data. More...
void | stp_set_errdata (stp_vars_t *v, void *val)
| Set the error data. More...
void * | stp_get_errdata (const stp_vars_t *v)
| Get the error data. More...
void | stp_set_dbgdata (stp_vars_t *v, void *val)
| Set the debug output data. More...
void * | stp_get_dbgdata (const stp_vars_t *v)
| Get the debug output data. More...
void | stp_merge_printvars (stp_vars_t *user, const stp_vars_t *print)
| Merge defaults for a printer with user-chosen settings. More...
void | stp_copy_vars_from (stp_vars_t *to, const stp_vars_t *from)
| Copy settings from one vars object to another, not modifying anything unset in the source. More...
stp_parameter_list_t | stp_get_parameter_list (const stp_vars_t *v)
| List the available parameters for the currently chosen settings. More...
size_t | stp_parameter_list_count (stp_const_parameter_list_t list)
| List the number of available parameters for the currently chosen settings. More...
const stp_parameter_t * | stp_parameter_find (stp_const_parameter_list_t list, const char *name)
| Find a parameter by its name. More...
const stp_parameter_t * | stp_parameter_list_param (stp_const_parameter_list_t list, size_t item)
| Find a parameter by its index number. More...
void | stp_parameter_list_destroy (stp_parameter_list_t list)
| Destroy a parameter_list. More...
stp_parameter_list_t | stp_parameter_list_create (void)
| Create a parameter_list. More...
void | stp_parameter_list_add_param (stp_parameter_list_t list, const stp_parameter_t *item)
| Add a parameter to a parameter_list. More...
stp_parameter_list_t | stp_parameter_list_copy (stp_const_parameter_list_t list)
| Copy and allocate a parameter_list. More...
void | stp_parameter_list_append (stp_parameter_list_t list, stp_const_parameter_list_t append)
| Append one parameter_list to another. More...
void | stp_describe_parameter (const stp_vars_t *v, const char *name, stp_parameter_t *description)
| Describe a parameter in detail. More...
void | stp_parameter_description_destroy (stp_parameter_t *description)
| Destroy a parameter description. More...
const stp_parameter_t * | stp_parameter_find_in_settings (const stp_vars_t *v, const char *name)
| Find a parameter by its name from a vars object. More...
void | stp_set_string_parameter (stp_vars_t *v, const char *parameter, const char *value)
| Set a string parameter. More...
void | stp_set_string_parameter_n (stp_vars_t *v, const char *parameter, const char *value, size_t bytes)
| Set a string parameter. More...
void | stp_set_file_parameter (stp_vars_t *v, const char *parameter, const char *value)
| Set a file parameter. More...
void | stp_set_file_parameter_n (stp_vars_t *v, const char *parameter, const char *value, size_t bytes)
| Set a file parameter. More...
void | stp_set_float_parameter (stp_vars_t *v, const char *parameter, double value)
| Set a float parameter. More...
void | stp_set_int_parameter (stp_vars_t *v, const char *parameter, int value)
| Set an integer parameter. More...
void | stp_set_dimension_parameter (stp_vars_t *v, const char *parameter, stp_dimension_t value)
| Set a dimension parameter. More...
void | stp_set_boolean_parameter (stp_vars_t *v, const char *parameter, int value)
| Set a boolean parameter. More...
void | stp_set_curve_parameter (stp_vars_t *v, const char *parameter, const stp_curve_t *value)
| Set a curve parameter. More...
void | stp_set_array_parameter (stp_vars_t *v, const char *parameter, const stp_array_t *value)
| Set an array parameter. More...
void | stp_set_raw_parameter (stp_vars_t *v, const char *parameter, const void *value, size_t bytes)
| Set a raw parameter. More...
void | stp_scale_float_parameter (stp_vars_t *v, const char *parameter, double scale)
| Multiply the value of a float parameter by a scaling factor. More...
void | stp_set_default_string_parameter (stp_vars_t *v, const char *parameter, const char *value)
| Set a default string parameter. More...
void | stp_set_default_string_parameter_n (stp_vars_t *v, const char *parameter, const char *value, size_t bytes)
| Set a default string parameter. More...
void | stp_set_default_file_parameter (stp_vars_t *v, const char *parameter, const char *value)
| Set a default file parameter. More...
void | stp_set_default_file_parameter_n (stp_vars_t *v, const char *parameter, const char *value, size_t bytes)
| Set a default file parameter. More...
void | stp_set_default_float_parameter (stp_vars_t *v, const char *parameter, double value)
| Set a default float parameter. More...
void | stp_set_default_int_parameter (stp_vars_t *v, const char *parameter, int value)
| Set a default integer parameter. More...
void | stp_set_default_dimension_parameter (stp_vars_t *v, const char *parameter, stp_dimension_t value)
| Set a default dimension parameter. More...
void | stp_set_default_boolean_parameter (stp_vars_t *v, const char *parameter, int value)
| Set a default boolean parameter. More...
void | stp_set_default_curve_parameter (stp_vars_t *v, const char *parameter, const stp_curve_t *value)
| Set a default curve parameter. More...
void | stp_set_default_array_parameter (stp_vars_t *v, const char *parameter, const stp_array_t *value)
| Set a default array parameter. More...
void | stp_set_default_raw_parameter (stp_vars_t *v, const char *parameter, const void *value, size_t bytes)
| Set a default raw parameter. More...
const char * | stp_get_string_parameter (const stp_vars_t *v, const char *parameter)
| Get a string parameter. More...
const char * | stp_get_file_parameter (const stp_vars_t *v, const char *parameter)
| Get a file parameter. More...
double | stp_get_float_parameter (const stp_vars_t *v, const char *parameter)
| Get a float parameter. More...
int | stp_get_int_parameter (const stp_vars_t *v, const char *parameter)
| Get an integer parameter. More...
stp_dimension_t | stp_get_dimension_parameter (const stp_vars_t *v, const char *parameter)
| Get a dimension parameter. More...
int | stp_get_boolean_parameter (const stp_vars_t *v, const char *parameter)
| Get a boolean parameter. More...
const stp_curve_t * | stp_get_curve_parameter (const stp_vars_t *v, const char *parameter)
| Get a curve parameter. More...
const stp_array_t * | stp_get_array_parameter (const stp_vars_t *v, const char *parameter)
| Get an array parameter. More...
const stp_raw_t * | stp_get_raw_parameter (const stp_vars_t *v, const char *parameter)
| Get a raw parameter. More...
void | stp_clear_string_parameter (stp_vars_t *v, const char *parameter)
| Clear a string parameter. More...
void | stp_clear_file_parameter (stp_vars_t *v, const char *parameter)
| Clear a file parameter. More...
void | stp_clear_float_parameter (stp_vars_t *v, const char *parameter)
| Clear (remove) a float parameter. More...
void | stp_clear_int_parameter (stp_vars_t *v, const char *parameter)
| Clear (remove) an integer parameter. More...
void | stp_clear_dimension_parameter (stp_vars_t *v, const char *parameter)
| Clear (remove) a dimension parameter. More...
void | stp_clear_boolean_parameter (stp_vars_t *v, const char *parameter)
| Clear (remove) a boolean parameter. More...
void | stp_clear_curve_parameter (stp_vars_t *v, const char *parameter)
| Clear a curve parameter. More...
void | stp_clear_array_parameter (stp_vars_t *v, const char *parameter)
| Clear an array parameter. More...
void | stp_clear_raw_parameter (stp_vars_t *v, const char *parameter)
| Clear a raw parameter. More...
void | stp_clear_parameter (stp_vars_t *v, const char *parameter, stp_parameter_type_t type)
| Clear a parameter. More...
stp_string_list_t * | stp_list_string_parameters (const stp_vars_t *v)
| List all string parameters. More...
stp_string_list_t * | stp_list_file_parameters (const stp_vars_t *v)
| List all file parameters. More...
stp_string_list_t * | stp_list_float_parameters (const stp_vars_t *v)
| List all float parameters. More...
stp_string_list_t * | stp_list_int_parameters (const stp_vars_t *v)
| List all integer parameters. More...
stp_string_list_t * | stp_list_dimension_parameters (const stp_vars_t *v)
| List all dimension parameters. More...
stp_string_list_t * | stp_list_boolean_parameters (const stp_vars_t *v)
| List all boolean parameters. More...
stp_string_list_t * | stp_list_curve_parameters (const stp_vars_t *v)
| List all curve parameters. More...
stp_string_list_t * | stp_list_array_parameters (const stp_vars_t *v)
| List all array parameters. More...
stp_string_list_t * | stp_list_raw_parameters (const stp_vars_t *v)
| List all raw parameters. More...
stp_string_list_t * | stp_list_parameters (const stp_vars_t *v, stp_parameter_type_t type)
| List all parameters. More...
void | stp_set_string_parameter_active (stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Set the activity of a string parameter. More...
void | stp_set_file_parameter_active (stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Set the activity of a file parameter. More...
void | stp_set_float_parameter_active (stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Set the activity of a float parameter. More...
void | stp_set_int_parameter_active (stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Set the activity of an integer parameter. More...
void | stp_set_dimension_parameter_active (stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Set the activity of a dimension parameter. More...
void | stp_set_boolean_parameter_active (stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Set the activity of a boolean parameter. More...
void | stp_set_curve_parameter_active (stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Set the activity of a curveparameter. More...
void | stp_set_array_parameter_active (stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Set the activity of an array parameter. More...
void | stp_set_raw_parameter_active (stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Set the activity of a raw parameter. More...
void | stp_set_parameter_active (stp_vars_t *v, const char *parameter, stp_parameter_activity_t active, stp_parameter_type_t type)
| Set the activity of a parameter. More...
int | stp_check_string_parameter (const stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Check if a string parameter is set. More...
int | stp_check_file_parameter (const stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Check if a file parameter is set. More...
int | stp_check_float_parameter (const stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Check if a float parameter is set. More...
int | stp_check_int_parameter (const stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Check if an integer parameter is set. More...
int | stp_check_dimension_parameter (const stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Check if a dimension parameter is set. More...
int | stp_check_boolean_parameter (const stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Check if a boolean parameter is set. More...
int | stp_check_curve_parameter (const stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Check if a curve parameter is set. More...
int | stp_check_array_parameter (const stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Check if an array parameter is set. More...
int | stp_check_raw_parameter (const stp_vars_t *v, const char *parameter, stp_parameter_activity_t active)
| Check if a raw parameter is set. More...
int | stp_check_parameter (const stp_vars_t *v, const char *parameter, stp_parameter_activity_t active, stp_parameter_type_t type)
| Check if a parameter is set. More...
stp_parameter_activity_t | stp_get_string_parameter_active (const stp_vars_t *v, const char *parameter)
| Get the activity status of a string parameter. More...
stp_parameter_activity_t | stp_get_file_parameter_active (const stp_vars_t *v, const char *parameter)
| Get the activity status of a file parameter. More...
stp_parameter_activity_t | stp_get_float_parameter_active (const stp_vars_t *v, const char *parameter)
| Get the activity status of a float parameter. More...
stp_parameter_activity_t | stp_get_int_parameter_active (const stp_vars_t *v, const char *parameter)
| Get the activity status of an integer parameter. More...
stp_parameter_activity_t | stp_get_dimension_parameter_active (const stp_vars_t *v, const char *parameter)
| Get the activity status of a dimension parameter. More...
stp_parameter_activity_t | stp_get_boolean_parameter_active (const stp_vars_t *v, const char *parameter)
| Get the activity status of a boolean parameter. More...
stp_parameter_activity_t | stp_get_curve_parameter_active (const stp_vars_t *v, const char *parameter)
| Get the activity status of a curve parameter. More...
stp_parameter_activity_t | stp_get_array_parameter_active (const stp_vars_t *v, const char *parameter)
| Get the activity status of an array parameter. More...
stp_parameter_activity_t | stp_get_raw_parameter_active (const stp_vars_t *v, const char *parameter)
| Get the activity status of a raw parameter. More...
stp_parameter_activity_t | stp_get_parameter_active (const stp_vars_t *v, const char *parameter, stp_parameter_type_t type)
| Get the activity status of a parameter. More...
void | stp_get_media_size (const stp_vars_t *v, stp_dimension_t *width, stp_dimension_t *height)
| Get the media (paper) size. More...
void | stp_get_imageable_area (const stp_vars_t *v, stp_dimension_t *left, stp_dimension_t *right, stp_dimension_t *bottom, stp_dimension_t *top)
| Get the imagable area of the page. More...
void | stp_get_maximum_imageable_area (const stp_vars_t *v, stp_dimension_t *left, stp_dimension_t *right, stp_dimension_t *bottom, stp_dimension_t *top)
| Get the maximum imagable area of the page. More...
void | stp_get_size_limit (const stp_vars_t *v, stp_dimension_t *max_width, stp_dimension_t *max_height, stp_dimension_t *min_width, stp_dimension_t *min_height)
| Get the media size limits. More...
void | stp_describe_resolution (const stp_vars_t *v, stp_resolution_t *x, stp_resolution_t *y)
| Retrieve the printing resolution of the selected resolution. More...
int | stp_verify (stp_vars_t *v)
| Verify parameters. More...
const stp_vars_t * | stp_default_settings (void)
| Get default global settings. More...
char * | stp_parameter_get_category (const stp_vars_t *v, const stp_parameter_t *desc, const char *category)
| Get the value of a specified category for the specified parameter. More...
int | stp_parameter_has_category_value (const stp_vars_t *v, const stp_parameter_t *desc, const char *category, const char *value)
| Determine whether a parameter has a category with the specified value. More...
stp_string_list_t * | stp_parameter_get_categories (const stp_vars_t *v, const stp_parameter_t *desc)
| Get the list of categories and their values for the specified parameter. More...
void | stp_allocate_component_data (stp_vars_t *v, const char *name, stp_copy_data_func_t copyfunc, stp_free_data_func_t freefunc, void *data)
void | stp_destroy_component_data (stp_vars_t *v, const char *name)
void * | stp_get_component_data (const stp_vars_t *v, const char *name)
stp_parameter_verify_t | stp_verify_parameter (const stp_vars_t *v, const char *parameter, int quiet)
int | stp_get_verified (const stp_vars_t *v)
void | stp_set_verified (stp_vars_t *v, int value)
void | stp_copy_options (stp_vars_t *vd, const stp_vars_t *vs)
void | stp_fill_parameter_settings (stp_parameter_t *desc, const stp_parameter_t *param)

## Detailed Description

The vars data type contains all the information about a print job, this includes information such as the printer model, paper size, print resolution etc.

Most of these job options are expressed as parameters which vary according to the model and other options selected.

The representation of printer settings has changed dramatically from 4.2. All (well most, anyway) settings outside of basics such as the printer model and sizing settings are now typed parameters.

## Macro Definition Documentation

## STP_CHANNEL_NONE

#define STP_CHANNEL_NONE ((unsigned char) -1)

## STP_RAW

#define STP_RAW | ( |  | x | ) | { sizeof((x)), (x) }

## STP_RAW_STRING

#define STP_RAW_STRING | ( |  | x | ) | { sizeof((x)) - 1, (x) }

## Typedef Documentation

## compdata_t

typedef struct stp_compdata compdata_t

## stp_const_parameter_list_t

typedef const void* stp_const_parameter_list_t

The constant parameter_list opaque data type.

## stp_copy_data_func_t

typedef void*(* stp_copy_data_func_t) (void *)

## stp_free_data_func_t

typedef void(* stp_free_data_func_t) (void *)

## stp_outfunc_t

typedef void(* stp_outfunc_t) (void *data, const char *buffer, size_t bytes)

Output function supplied by the calling application.

There are two output functions supplied by the caller, one to send output data and one to report errors.

Parameters

  data | a pointer to an opaque object owned by the calling application.
  buffer | the data to output.
  bytes | the size of buffer (in bytes).

## stp_parameter_list_t

typedef void* stp_parameter_list_t

The parameter_list opaque data type.

## stp_vars_t

typedef struct stp_vars stp_vars_t

The vars opaque data type.

## Enumeration Type Documentation

## stp_parameter_activity_t

enum stp_parameter_activity_t

Parameter activity.

Whether a parameter is currently active (i. e. whether its value should be used by the driver or not). All parameters default to being active unless explicitly "turned off".

Enumerator
STP_PARAMETER_INACTIVE | Parameter is inactive (unused).
STP_PARAMETER_DEFAULTED | Parameter is set to its default value.
STP_PARAMETER_ACTIVE | Parameter is active (used).

## stp_parameter_class_t

enum stp_parameter_class_t

Parameter class.

What kind of setting this is, for the purpose of user interface representation.

Enumerator
STP_PARAMETER_CLASS_FEATURE | Printer feature.
STP_PARAMETER_CLASS_OUTPUT | Output control.
STP_PARAMETER_CLASS_CORE | Core Gimp-Print parameter.
STP_PARAMETER_CLASS_INVALID | Invalid class (should never be used).

## stp_parameter_level_t

enum stp_parameter_level_t

Parameter level.

What "level" a setting is at, for UI design.

Enumerator
STP_PARAMETER_LEVEL_BASIC | Basic parameter, shown by all UIs.
STP_PARAMETER_LEVEL_ADVANCED | Advanced parameter, shown by advanced UIs.
STP_PARAMETER_LEVEL_ADVANCED1 | Advanced1 parameter, shown by advanced UIs.
STP_PARAMETER_LEVEL_ADVANCED2 | Advanced2 parameter, shown by advanced UIs.
STP_PARAMETER_LEVEL_ADVANCED3 | Advanced3 parameter, shown by advanced UIs.
STP_PARAMETER_LEVEL_ADVANCED4 | Advanced4 parameter, shown by advanced UIs.
STP_PARAMETER_LEVEL_INTERNAL | Parameters used only within Gimp-Print.
STP_PARAMETER_LEVEL_EXTERNAL | Parameters used only outside Gimp-Print.
STP_PARAMETER_LEVEL_INVALID | Invalid level (should never be used).

## stp_parameter_type_t

enum stp_parameter_type_t

Parameter types.

The following types are permitted for a printer setting. Not all are currently implemented.

Enumerator
STP_PARAMETER_TYPE_STRING_LIST | Single string choice from a list.
STP_PARAMETER_TYPE_INT | Integer.
STP_PARAMETER_TYPE_BOOLEAN | Boolean.
STP_PARAMETER_TYPE_DOUBLE | Floating point number.
STP_PARAMETER_TYPE_CURVE | Curve.
STP_PARAMETER_TYPE_FILE | Filename (NYI, need to consider security).
STP_PARAMETER_TYPE_RAW | Raw, opaque data.
STP_PARAMETER_TYPE_ARRAY | Array.
STP_PARAMETER_TYPE_DIMENSION | Linear dimension.
STP_PARAMETER_TYPE_INVALID | Invalid type (should never be used).

## stp_parameter_verify_t

enum stp_parameter_verify_t

Enumerator
PARAMETER_BAD |
PARAMETER_OK |
PARAMETER_INACTIVE |

## Function Documentation

## stp_allocate_component_data()

void stp_allocate_component_data | ( | stp_vars_t * | v,
|  | const char * | name,
|  | stp_copy_data_func_t | copyfunc,
|  | stp_free_data_func_t | freefunc,
|  | void * | data
| ) |  |

## stp_check_array_parameter()

int stp_check_array_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Check if an array parameter is set.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the minimum activity status.

## stp_check_boolean_parameter()

int stp_check_boolean_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Check if a boolean parameter is set.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the minimum activity status.

## stp_check_curve_parameter()

int stp_check_curve_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Check if a curve parameter is set.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the minimum activity status.

## stp_check_dimension_parameter()

int stp_check_dimension_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Check if a dimension parameter is set.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the minimum activity status.

## stp_check_file_parameter()

int stp_check_file_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Check if a file parameter is set.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the minimum activity status.

## stp_check_float_parameter()

int stp_check_float_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Check if a float parameter is set.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the minimum activity status.

## stp_check_int_parameter()

int stp_check_int_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Check if an integer parameter is set.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the minimum activity status.

## stp_check_parameter()

int stp_check_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active,
|  | stp_parameter_type_t | type
| ) |  |

Check if a parameter is set.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the minimum activity status.
  type | the type of the parameter.

## stp_check_raw_parameter()

int stp_check_raw_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Check if a raw parameter is set.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the minimum activity status.

## stp_check_string_parameter()

int stp_check_string_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Check if a string parameter is set.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the minimum activity status.

## stp_clear_array_parameter()

void stp_clear_array_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Clear an array parameter.

The parameter is set to NULL.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

## stp_clear_boolean_parameter()

void stp_clear_boolean_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Clear (remove) a boolean parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

## stp_clear_curve_parameter()

void stp_clear_curve_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Clear a curve parameter.

The parameter is set to NULL.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

## stp_clear_dimension_parameter()

void stp_clear_dimension_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Clear (remove) a dimension parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

## stp_clear_file_parameter()

void stp_clear_file_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Clear a file parameter.

The parameter is set to NULL.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

## stp_clear_float_parameter()

void stp_clear_float_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Clear (remove) a float parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

## stp_clear_int_parameter()

void stp_clear_int_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Clear (remove) an integer parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

## stp_clear_parameter()

void stp_clear_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_type_t | type
| ) |  |

Clear a parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  type | the type of the parameter.

## stp_clear_raw_parameter()

void stp_clear_raw_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Clear a raw parameter.

The parameter is set to NULL.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

## stp_clear_string_parameter()

void stp_clear_string_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Clear a string parameter.

The parameter is set to NULL.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

## stp_copy_options()

void stp_copy_options | ( | stp_vars_t * | vd,
|  | const stp_vars_t * | vs
| ) |  |

## stp_copy_vars_from()

void stp_copy_vars_from | ( | stp_vars_t * | to,
|  | const stp_vars_t * | from
| ) |  |

Copy settings from one vars object to another, not modifying anything unset in the source.

Parameters

  to | the destination vars.
  from | the vars to merge into user.

## stp_default_settings()

const stp_vars_t* stp_default_settings | ( | void |  | ) |

Get default global settings.

The main use of this is to provide a usable stp_vars_t for purposes of parameter inquiry in the absence of a specific printer. This is currently used in a variety of places to get information on the standard color parameters without querying a particular printer.

Returns
  the default settings.

## stp_describe_parameter()

void stp_describe_parameter | ( | const stp_vars_t * | v,
|  | const char * | name,
|  | stp_parameter_t * | description
| ) |  |

Describe a parameter in detail.

All of the parameter fields will be populated.

Parameters

  v | the vars to use.
  name | the name of the parameter.
  description | a pointer to an stp_parameter_t to store the parameter description in.

## stp_describe_resolution()

void stp_describe_resolution | ( | const stp_vars_t * | v,
|  | stp_resolution_t * | x,
|  | stp_resolution_t * | y
| ) |  |

Retrieve the printing resolution of the selected resolution.

If the resolution is invalid, -1 will be returned in both x and y.

Parameters

  v | the vars to use.
  x | a pointer to a stp_resolution_t to store the horizontal resolution in.
  y | a pointer to a stp_resolution_t to store the vertical resolution in.

## stp_destroy_component_data()

void stp_destroy_component_data | ( | stp_vars_t * | v,
|  | const char * | name
| ) |  |

## stp_fill_parameter_settings()

void stp_fill_parameter_settings | ( | stp_parameter_t * | desc,
|  | const stp_parameter_t * | param
| ) |  |

## stp_get_array_parameter()

const stp_array_t* stp_get_array_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get an array parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the array, or NULL if no parameter was found.

## stp_get_array_parameter_active()

stp_parameter_activity_t stp_get_array_parameter_active | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get the activity status of an array parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the activity status.

## stp_get_boolean_parameter()

int stp_get_boolean_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get a boolean parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the boolean value.

## stp_get_boolean_parameter_active()

stp_parameter_activity_t stp_get_boolean_parameter_active | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get the activity status of a boolean parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the activity status.

## stp_get_color_conversion()

const char* stp_get_color_conversion | ( | const stp_vars_t * | v | ) |

Get the name of the color conversion routine.

Returns
  the name of the color conversion routine (must not be freed).

## stp_get_component_data()

void* stp_get_component_data | ( | const stp_vars_t * | v,
|  | const char * | name
| ) |  |

## stp_get_curve_parameter()

const stp_curve_t* stp_get_curve_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get a curve parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the curve, or NULL if no parameter was found.

## stp_get_curve_parameter_active()

stp_parameter_activity_t stp_get_curve_parameter_active | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get the activity status of a curve parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the activity status.

## stp_get_dbgdata()

void* stp_get_dbgdata | ( | const stp_vars_t * | v | ) |

Get the debug output data.

Parameters

  v | the vars to use.

Returns
  the output data.

## stp_get_dbgfunc()

stp_outfunc_t stp_get_dbgfunc | ( | const stp_vars_t * | v | ) |

Get the function used to print output information.

Parameters

  v | the vars to use.

Returns
  the outfunc.

## stp_get_dimension_parameter()

stp_dimension_t stp_get_dimension_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get a dimension parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the dimension (integer) value.

## stp_get_dimension_parameter_active()

stp_parameter_activity_t stp_get_dimension_parameter_active | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get the activity status of a dimension parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the activity status.

## stp_get_driver()

const char* stp_get_driver | ( | const stp_vars_t * | v | ) |

Get the name of the printer driver.

Returns
  the name of the printer driver (must not be freed).

## stp_get_errdata()

void* stp_get_errdata | ( | const stp_vars_t * | v | ) |

Get the error data.

Parameters

  v | the vars to use.

Returns
  the output data.

## stp_get_errfunc()

stp_outfunc_t stp_get_errfunc | ( | const stp_vars_t * | v | ) |

Get the function used to print output information.

Parameters

  v | the vars to use.

Returns
  the outfunc.

## stp_get_file_parameter()

const char* stp_get_file_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get a file parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the filename, or NULL if no parameter was found.

## stp_get_file_parameter_active()

stp_parameter_activity_t stp_get_file_parameter_active | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get the activity status of a file parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the activity status.

## stp_get_float_parameter()

double stp_get_float_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get a float parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the float value.

## stp_get_float_parameter_active()

stp_parameter_activity_t stp_get_float_parameter_active | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get the activity status of a float parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the activity status.

## stp_get_height()

stp_dimension_t stp_get_height | ( | const stp_vars_t * | v | ) |

Get the height of the image.

Returns
  the left edge.

## stp_get_imageable_area()

void stp_get_imageable_area | ( | const stp_vars_t * | v,
|  | stp_dimension_t * | left,
|  | stp_dimension_t * | right,
|  | stp_dimension_t * | bottom,
|  | stp_dimension_t * | top
| ) |  |

Get the imagable area of the page.

Retrieve the boundaries of the printable area of the page. In combination with the media size, this can be used to determine the actual printable region, which callers can use to place the image precisely. The dimensions are relative to the top left of the physical page.

If a customizable page size is used (see stp_printer_get_media_size), the actual desired width and/or height must be filled in using stp_set_page_width and/or stp_set_page_height. If these are not filled in, the margins will be returned.

Returned values may be negative if a printer is capable of full bleed by printing beyond the physical boundaries of the page.

If the media size stored in V is invalid, the return values will be indeterminate. It is up to the user to specify legal values.

Parameters

  v | the vars to use.
  left | a pointer to a stp_dimension_t to store the left edge in.
  right | a pointer to a stp_dimension_t to store the right edge in.
  bottom | a pointer to a stp_dimension_t to store the bottom edge in.
  top | a pointer to a stp_dimension_t to store the top edge in.

## stp_get_int_parameter()

int stp_get_int_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get an integer parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the integer value.

## stp_get_int_parameter_active()

stp_parameter_activity_t stp_get_int_parameter_active | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get the activity status of an integer parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the activity status.

## stp_get_left()

stp_dimension_t stp_get_left | ( | const stp_vars_t * | v | ) |

Get the left edge of the image.

Returns
  the left edge.

## stp_get_maximum_imageable_area()

void stp_get_maximum_imageable_area | ( | const stp_vars_t * | v,
|  | stp_dimension_t * | left,
|  | stp_dimension_t * | right,
|  | stp_dimension_t * | bottom,
|  | stp_dimension_t * | top
| ) |  |

Get the maximum imagable area of the page.

Retrieve the maximum (regardless of settings other than page sise) boundaries of the printable area of the page. In combination with the media size, this can be used to determine the actual printable region, which callers can use to place the image precisely. The dimensions are relative to the top left of the physical page.

If a customizable page size is used (see stp_printer_get_media_size), the actual desired width and/or height must be filled in using stp_set_page_width and/or stp_set_page_height. If these are not filled in, the margins will be returned.

Returned values may be negative if a printer is capable of full bleed by printing beyond the physical boundaries of the page.

If the media size stored in V is invalid, the return values will be indeterminate. It is up to the user to specify legal values.

Parameters

  v | the vars to use.
  left | a pointer to a stp_dimension_t to store the left edge in.
  right | a pointer to a stp_dimension_t to store the right edge in.
  bottom | a pointer to a stp_dimension_t to store the bottom edge in.
  top | a pointer to a stp_dimension_t to store the top edge in.

## stp_get_media_size()

void stp_get_media_size | ( | const stp_vars_t * | v,
|  | stp_dimension_t * | width,
|  | stp_dimension_t * | height
| ) |  |

Get the media (paper) size.

Retrieve the media size of the media type set in V, expressed in units of 1/72". If the media size is invalid, width and height will be set to -1. Values of 0 for width or height indicate that the dimension is variable, so that custom page sizes or roll paper can be used. In this case, the size limit should be used to determine maximum and minimum values permitted.

Parameters

  v | the vars to use.
  width | a pointer to an stp_dimension_t to store the media width in.
  height | a pointer to an stp_dimension_t to store the media height in.

## stp_get_outdata()

void* stp_get_outdata | ( | const stp_vars_t * | v | ) |

Get the output data.

Parameters

  v | the vars to use.

Returns
  the output data.

## stp_get_outfunc()

stp_outfunc_t stp_get_outfunc | ( | const stp_vars_t * | v | ) |

Get the function used to print output information.

Parameters

  v | the vars to use.

Returns
  the outfunc.

## stp_get_page_height()

stp_dimension_t stp_get_page_height | ( | const stp_vars_t * | v | ) |

Get the page height.

Returns
  the page height.

## stp_get_page_width()

stp_dimension_t stp_get_page_width | ( | const stp_vars_t * | v | ) |

Get the page width.

Returns
  the page width.

## stp_get_parameter_active()

stp_parameter_activity_t stp_get_parameter_active | ( | const stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_type_t | type
| ) |  |

Get the activity status of a parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  type | the type of the parameter.

## stp_get_parameter_list()

stp_parameter_list_t stp_get_parameter_list | ( | const stp_vars_t * | v | ) |

List the available parameters for the currently chosen settings.

This does not fill in the bounds and defaults; it merely provides a list of settings. To fill in detailed information for a setting, use stp_describe_parameter.

Parameters

  v | the vars to use.

Returns
  a list of available parameters (must be freed with stp_parameter_list_destroy()).

## stp_get_raw_parameter()

const stp_raw_t* stp_get_raw_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get a raw parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the raw data, or NULL if no parameter was found.

## stp_get_raw_parameter_active()

stp_parameter_activity_t stp_get_raw_parameter_active | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get the activity status of a raw parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the activity status.

## stp_get_size_limit()

void stp_get_size_limit | ( | const stp_vars_t * | v,
|  | stp_dimension_t * | max_width,
|  | stp_dimension_t * | max_height,
|  | stp_dimension_t * | min_width,
|  | stp_dimension_t * | min_height
| ) |  |

Get the media size limits.

Retrieve the minimum and maximum size limits for custom media sizes with the current printer settings.

Parameters

  v | the vars to use.
  max_width | a pointer to a stp_dimension_t to store the maximum width in.
  max_height | a pointer to a stp_dimension_t to store the maximum height in.
  min_width | a pointer to a stp_dimension_t to store the minimum width in.
  min_height | a pointer to a stp_dimension_t to store the minimum height in.

## stp_get_string_parameter()

const char* stp_get_string_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get a string parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the string, or NULL if no parameter was found.

## stp_get_string_parameter_active()

stp_parameter_activity_t stp_get_string_parameter_active | ( | const stp_vars_t * | v,
|  | const char * | parameter
| ) |  |

Get the activity status of a string parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.

Returns
  the activity status.

## stp_get_top()

stp_dimension_t stp_get_top | ( | const stp_vars_t * | v | ) |

Get the top edge of the image.

Returns
  the left edge.

## stp_get_verified()

int stp_get_verified | ( | const stp_vars_t * | v | ) |

## stp_get_width()

stp_dimension_t stp_get_width | ( | const stp_vars_t * | v | ) |

Get the width edge of the image.

Returns
  the left edge.

## stp_list_array_parameters()

stp_string_list_t* stp_list_array_parameters | ( | const stp_vars_t * | v | ) |

List all array parameters.

The return value must be freed after use.

Parameters

  v | the vars to use.

## stp_list_boolean_parameters()

stp_string_list_t* stp_list_boolean_parameters | ( | const stp_vars_t * | v | ) |

List all boolean parameters.

The return value must be freed after use.

Parameters

  v | the vars to use.

## stp_list_curve_parameters()

stp_string_list_t* stp_list_curve_parameters | ( | const stp_vars_t * | v | ) |

List all curve parameters.

The return value must be freed after use.

Parameters

  v | the vars to use.

## stp_list_dimension_parameters()

stp_string_list_t* stp_list_dimension_parameters | ( | const stp_vars_t * | v | ) |

List all dimension parameters.

The return value must be freed after use.

Parameters

  v | the vars to use.

## stp_list_file_parameters()

stp_string_list_t* stp_list_file_parameters | ( | const stp_vars_t * | v | ) |

List all file parameters.

The return value must be freed after use.

Parameters

  v | the vars to use.

## stp_list_float_parameters()

stp_string_list_t* stp_list_float_parameters | ( | const stp_vars_t * | v | ) |

List all float parameters.

The return value must be freed after use.

Parameters

  v | the vars to use.

## stp_list_int_parameters()

stp_string_list_t* stp_list_int_parameters | ( | const stp_vars_t * | v | ) |

List all integer parameters.

The return value must be freed after use.

Parameters

  v | the vars to use.

## stp_list_parameters()

stp_string_list_t* stp_list_parameters | ( | const stp_vars_t * | v,
|  | stp_parameter_type_t | type
| ) |  |

List all parameters.

The return value must be freed after use.

Parameters

  v | the vars to use.
  type | the type of the parameter.

## stp_list_raw_parameters()

stp_string_list_t* stp_list_raw_parameters | ( | const stp_vars_t * | v | ) |

List all raw parameters.

The return value must be freed after use.

Parameters

  v | the vars to use.

## stp_list_string_parameters()

stp_string_list_t* stp_list_string_parameters | ( | const stp_vars_t * | v | ) |

List all string parameters.

The return value must be freed after use.

Parameters

  v | the vars to use.

## stp_merge_printvars()

void stp_merge_printvars | ( | stp_vars_t * | user,
|  | const stp_vars_t * | print
| ) |  |

Merge defaults for a printer with user-chosen settings.

Deprecated:
  This is likely to go away.

Parameters

  user | the destination vars.
  print | the vars to merge into user.

## stp_parameter_description_destroy()

void stp_parameter_description_destroy | ( | stp_parameter_t * | description | ) |

Destroy a parameter description.

This must be called even if the stp_parameter_t was not allocated with malloc, since some members are dynamically allocated.

Parameters

  description | the parameter description to destroy.

## stp_parameter_find()

const stp_parameter_t* stp_parameter_find | ( | stp_const_parameter_list_t | list,
|  | const char * | name
| ) |  |

Find a parameter by its name.

Parameters

  list | the parameter_list to use.
  name | the name of the parameter.

Returns
  a pointer to the parameter (must not be freed), or NULL if no parameter was found.

## stp_parameter_find_in_settings()

const stp_parameter_t* stp_parameter_find_in_settings | ( | const stp_vars_t * | v,
|  | const char * | name
| ) |  |

Find a parameter by its name from a vars object.

Parameters

  v | the vars to use.
  name | the name of the parameter.

Returns
  a pointer to the parameter (must not be freed), or NULL if no parameter was found.

## stp_parameter_get_categories()

stp_string_list_t* stp_parameter_get_categories | ( | const stp_vars_t * | v,
|  | const stp_parameter_t * | desc
| ) |  |

Get the list of categories and their values for the specified parameter.

Parameters

  v | the vars to use.
  desc | the parameter description to use (must already be described)

Returns
  the list of categories.

## stp_parameter_get_category()

char* stp_parameter_get_category | ( | const stp_vars_t * | v,
|  | const stp_parameter_t * | desc,
|  | const char * | category
| ) |  |

Get the value of a specified category for the specified parameter.

Parameters

  v | the vars to use.
  desc | the parameter description to use (must already be described)
  category | the name of the category to search for.

Returns
  the value of the category or NULL. String must be freed by caller.

## stp_parameter_has_category_value()

int stp_parameter_has_category_value | ( | const stp_vars_t * | v,
|  | const stp_parameter_t * | desc,
|  | const char * | category,
|  | const char * | value
| ) |  |

Determine whether a parameter has a category with the specified value.

If a null value is passed in, return whether the parameter has the category at all. Return -1 if any other error condition (null vars, desc, or category).

Parameters

  v | the vars to use.
  desc | the parameter description to use (must already be described)
  category | the name of the category to search for.
  value | the value of the category to search for.

Returns
  whether the parameter has the category with the specified value.

## stp_parameter_list_add_param()

void stp_parameter_list_add_param | ( | stp_parameter_list_t | list,
|  | const stp_parameter_t * | item
| ) |  |

Add a parameter to a parameter_list.

Parameters

  list | the parameter_list to use.
  item | the parameter to add.

## stp_parameter_list_append()

void stp_parameter_list_append | ( | stp_parameter_list_t | list,
|  | stp_const_parameter_list_t | append
| ) |  |

Append one parameter_list to another.

Parameters

  list | the destination list (to append to).
  append | the list of parameters to append. Each item that does not already exist in list will be appended.

## stp_parameter_list_copy()

stp_parameter_list_t stp_parameter_list_copy | ( | stp_const_parameter_list_t | list | ) |

Copy and allocate a parameter_list.

A new parameter_list will be created, and then the contents of source will be copied into it.

Parameters

  list | the source parameter_list.

Returns
  the new copy of the parameter_list.

## stp_parameter_list_count()

size_t stp_parameter_list_count | ( | stp_const_parameter_list_t | list | ) |

List the number of available parameters for the currently chosen settings.

Parameters

  list | the parameter_list to use.

Returns
  the number of parameters.

## stp_parameter_list_create()

stp_parameter_list_t stp_parameter_list_create | ( | void |  | ) |

Create a parameter_list.

Returns
  the newly created parameter_list.

## stp_parameter_list_destroy()

void stp_parameter_list_destroy | ( | stp_parameter_list_t | list | ) |

Destroy a parameter_list.

It is an error to destroy the parameter_list more than once.

Parameters

  list | the parameter_list to destroy.

## stp_parameter_list_param()

const stp_parameter_t* stp_parameter_list_param | ( | stp_const_parameter_list_t | list,
|  | size_t | item
| ) |  |

Find a parameter by its index number.

Parameters

  list | the parameter_list to use.
  item | the index number of the parameter (must not be greater than stp_parameter_list_count - 1).

Returns
  a pointer to the parameter (must not be freed), or NULL if no parameter was found.

## stp_scale_float_parameter()

void stp_scale_float_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | double | scale
| ) |  |

Multiply the value of a float parameter by a scaling factor.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  scale | the factor to multiply the value by.

## stp_set_array_parameter()

void stp_set_array_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | const stp_array_t * | value
| ) |  |

Set an array parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.

## stp_set_array_parameter_active()

void stp_set_array_parameter_active | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Set the activity of an array parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the activity status to set (should be set to STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).

## stp_set_boolean_parameter()

void stp_set_boolean_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | int | value
| ) |  |

Set a boolean parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.

## stp_set_boolean_parameter_active()

void stp_set_boolean_parameter_active | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Set the activity of a boolean parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the activity status to set (should be set to STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).

## stp_set_color_conversion()

void stp_set_color_conversion | ( | stp_vars_t * | v,
|  | const char * | val
| ) |  |

Set the name of the color conversion routine, if not the default.

Parameters

  v | the vars to use.
  val | the name to set.

## stp_set_color_conversion_n()

void stp_set_color_conversion_n | ( | stp_vars_t * | v,
|  | const char * | val,
|  | int | bytes
| ) |  |

Set the name of the color conversion routine, if not the default.

Parameters

  v | the vars to use.
  val | the name to set.
  bytes | the length of val (in bytes).

## stp_set_curve_parameter()

void stp_set_curve_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | const stp_curve_t * | value
| ) |  |

Set a curve parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.

## stp_set_curve_parameter_active()

void stp_set_curve_parameter_active | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Set the activity of a curveparameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the activity status to set (should be set to STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).

## stp_set_dbgdata()

void stp_set_dbgdata | ( | stp_vars_t * | v,
|  | void * | val
| ) |  |

Set the debug output data.

Parameters

  v | the vars to use.
  val | the debug data. This will typically be a file descriptor, but it is entirely up to the caller exactly what type this might be.

## stp_set_dbgfunc()

void stp_set_dbgfunc | ( | stp_vars_t * | v,
|  | stp_outfunc_t | val
| ) |  |

Set the function used to print diagnostic information.

These must be supplied by the caller. dbgdata is passed as an arguments to dbgfunc; typically it will be a file descriptor.

Parameters

  v | the vars to use.
  val | the value to set.

## stp_set_default_array_parameter()

void stp_set_default_array_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | const stp_array_t * | value
| ) |  |

Set a default array parameter.

The value is set if the parameter is not already set. This avoids having to check if the parameter is set prior to setting it, if you do not want to override the existing value.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.

## stp_set_default_boolean_parameter()

void stp_set_default_boolean_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | int | value
| ) |  |

Set a default boolean parameter.

The value is set if the parameter is not already set. This avoids having to check if the parameter is set prior to setting it, if you do not want to override the existing value.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.

## stp_set_default_curve_parameter()

void stp_set_default_curve_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | const stp_curve_t * | value
| ) |  |

Set a default curve parameter.

The value is set if the parameter is not already set. This avoids having to check if the parameter is set prior to setting it, if you do not want to override the existing value.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.

## stp_set_default_dimension_parameter()

void stp_set_default_dimension_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_dimension_t | value
| ) |  |

Set a default dimension parameter.

The value is set if the parameter is not already set. This avoids having to check if the parameter is set prior to setting it, if you do not want to override the existing value.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.

## stp_set_default_file_parameter()

void stp_set_default_file_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | const char * | value
| ) |  |

Set a default file parameter.

The value is set if the parameter is not already set. This avoids having to check if the parameter is set prior to setting it, if you do not want to override the existing value.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.

## stp_set_default_file_parameter_n()

void stp_set_default_file_parameter_n | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | const char * | value,
|  | size_t | bytes
| ) |  |

Set a default file parameter.

The value is set if the parameter is not already set. This avoids having to check if the parameter is set prior to setting it, if you do not want to override the existing value.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set (must not contain NUL).
  bytes | the length of value (in bytes).

## stp_set_default_float_parameter()

void stp_set_default_float_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | double | value
| ) |  |

Set a default float parameter.

The value is set if the parameter is not already set. This avoids having to check if the parameter is set prior to setting it, if you do not want to override the existing value.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.

## stp_set_default_int_parameter()

void stp_set_default_int_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | int | value
| ) |  |

Set a default integer parameter.

The value is set if the parameter is not already set. This avoids having to check if the parameter is set prior to setting it, if you do not want to override the existing value.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.

## stp_set_default_raw_parameter()

void stp_set_default_raw_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | const void * | value,
|  | size_t | bytes
| ) |  |

Set a default raw parameter.

The value is set if the parameter is not already set. This avoids having to check if the parameter is set prior to setting it, if you do not want to override the existing value.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.
  bytes | the length of value (in bytes).

## stp_set_default_string_parameter()

void stp_set_default_string_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | const char * | value
| ) |  |

Set a default string parameter.

The value is set if the parameter is not already set. This avoids having to check if the parameter is set prior to setting it, if you do not want to override the existing value.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.

## stp_set_default_string_parameter_n()

void stp_set_default_string_parameter_n | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | const char * | value,
|  | size_t | bytes
| ) |  |

Set a default string parameter.

The value is set if the parameter is not already set. This avoids having to check if the parameter is set prior to setting it, if you do not want to override the existing value.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set (must not contain NUL).
  bytes | the length of value (in bytes).

## stp_set_dimension_parameter()

void stp_set_dimension_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_dimension_t | value
| ) |  |

Set a dimension parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.

## stp_set_dimension_parameter_active()

void stp_set_dimension_parameter_active | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Set the activity of a dimension parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the activity status to set (should be set to STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).

## stp_set_driver()

void stp_set_driver | ( | stp_vars_t * | v,
|  | const char * | val
| ) |  |

Set the name of the printer driver.

Parameters

  v | the vars to use.
  val | the name to set.

## stp_set_driver_n()

void stp_set_driver_n | ( | stp_vars_t * | v,
|  | const char * | val,
|  | int | bytes
| ) |  |

Set the name of the printer driver.

Parameters

  v | the vars to use.
  val | the name to set.
  bytes | the length of val (in bytes).

## stp_set_errdata()

void stp_set_errdata | ( | stp_vars_t * | v,
|  | void * | val
| ) |  |

Set the error data.

Parameters

  v | the vars to use.
  val | the error data. This will typically be a file descriptor, but it is entirely up to the caller exactly what type this might be.

## stp_set_errfunc()

void stp_set_errfunc | ( | stp_vars_t * | v,
|  | stp_outfunc_t | val
| ) |  |

Set the function used to print error information.

These must be supplied by the caller. errdata is passed as an arguments to errfunc; typically it will be a file descriptor.

Parameters

  v | the vars to use.
  val | the value to set.

## stp_set_file_parameter()

void stp_set_file_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | const char * | value
| ) |  |

Set a file parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.

## stp_set_file_parameter_active()

void stp_set_file_parameter_active | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Set the activity of a file parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the activity status to set (should be set to STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).

## stp_set_file_parameter_n()

void stp_set_file_parameter_n | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | const char * | value,
|  | size_t | bytes
| ) |  |

Set a file parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set (must not contain NUL).
  bytes | the length of value (in bytes).

## stp_set_float_parameter()

void stp_set_float_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | double | value
| ) |  |

Set a float parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.

## stp_set_float_parameter_active()

void stp_set_float_parameter_active | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Set the activity of a float parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the activity status to set (should be set to STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).

## stp_set_height()

void stp_set_height | ( | stp_vars_t * | v,
|  | stp_dimension_t | val
| ) |  |

Set the height of the image.

Parameters

  v | the vars to use.
  val | the value to set.

## stp_set_int_parameter()

void stp_set_int_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | int | value
| ) |  |

Set an integer parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.

## stp_set_int_parameter_active()

void stp_set_int_parameter_active | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Set the activity of an integer parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the activity status to set (should be set to STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).

## stp_set_left()

void stp_set_left | ( | stp_vars_t * | v,
|  | stp_dimension_t | val
| ) |  |

Set the left edge of the image.

Parameters

  v | the vars to use.
  val | the value to set.

## stp_set_outdata()

void stp_set_outdata | ( | stp_vars_t * | v,
|  | void * | val
| ) |  |

Set the output data.

Parameters

  v | the vars to use.
  val | the output data. This will typically be a file descriptor, but it is entirely up to the caller exactly what type this might be.

## stp_set_outfunc()

void stp_set_outfunc | ( | stp_vars_t * | v,
|  | stp_outfunc_t | val
| ) |  |

Set the function used to print output information.

These must be supplied by the caller. outdata is passed as an arguments to outfunc; typically it will be a file descriptor.

Parameters

  v | the vars to use.
  val | the value to set.

## stp_set_page_height()

void stp_set_page_height | ( | stp_vars_t * | v,
|  | stp_dimension_t | val
| ) |  |

Set the page height.

Parameters

  v | the vars to use.
  val | the value to set.

## stp_set_page_width()

void stp_set_page_width | ( | stp_vars_t * | v,
|  | stp_dimension_t | val
| ) |  |

Set the page width.

Parameters

  v | the vars to use.
  val | the value to set.

## stp_set_parameter_active()

void stp_set_parameter_active | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active,
|  | stp_parameter_type_t | type
| ) |  |

Set the activity of a parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the activity status to set (should be set to STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).
  type | the type of the parameter.

## stp_set_raw_parameter()

void stp_set_raw_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | const void * | value,
|  | size_t | bytes
| ) |  |

Set a raw parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.
  bytes | the length of value (in bytes).

## stp_set_raw_parameter_active()

void stp_set_raw_parameter_active | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Set the activity of a raw parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the activity status to set (should be set to STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).

## stp_set_string_parameter()

void stp_set_string_parameter | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | const char * | value
| ) |  |

Set a string parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set.

## stp_set_string_parameter_active()

void stp_set_string_parameter_active | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | stp_parameter_activity_t | active
| ) |  |

Set the activity of a string parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  active | the activity status to set (should be set to STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).

## stp_set_string_parameter_n()

void stp_set_string_parameter_n | ( | stp_vars_t * | v,
|  | const char * | parameter,
|  | const char * | value,
|  | size_t | bytes
| ) |  |

Set a string parameter.

Parameters

  v | the vars to use.
  parameter | the name of the parameter.
  value | the value to set (must not contain NUL).
  bytes | the length of value (in bytes).

## stp_set_top()

void stp_set_top | ( | stp_vars_t * | v,
|  | stp_dimension_t | val
| ) |  |

Set the top edge of the image.

Parameters

  v | the vars to use.
  val | the value to set.

## stp_set_verified()

void stp_set_verified | ( | stp_vars_t * | v,
|  | int | value
| ) |  |

## stp_set_width()

void stp_set_width | ( | stp_vars_t * | v,
|  | stp_dimension_t | val
| ) |  |

Set the width of the image.

Parameters

  v | the vars to use.
  val | the value to set.

## stp_vars_copy()

void stp_vars_copy | ( | stp_vars_t * | dest,
|  | const stp_vars_t * | source
| ) |  |

Copy a vars object.

Both dest and source must be valid vars objects previously created with stp_vars_create().

Parameters

  dest | the destination vars.
  source | the source vars.

## stp_vars_create()

stp_vars_t* stp_vars_create | ( | void |  | ) |

Create a new vars object.

Returns
  the newly created vars object.

## stp_vars_create_copy()

stp_vars_t* stp_vars_create_copy | ( | const stp_vars_t * | source | ) |

Copy and allocate a vars object.

source must be a valid vars object previously created with stp_vars_create().

Parameters

  source | the source vars.

Returns
  the new copy of the vars.

## stp_vars_destroy()

void stp_vars_destroy | ( | stp_vars_t * | v | ) |

Destroy a vars object.

It is an error to destroy the vars more than once.

Parameters

  v | the vars to destroy.

## stp_vars_print_error()

void stp_vars_print_error | ( | const stp_vars_t * | v,
|  | const char * | prefix
| ) |  |

Print an stp_vars_t in debugging format.

Parameters

  v | stp_vars_t to dump
  prefix | Prefix to prepend to each line (null pointer gives empty prefix)

## stp_verify()

int stp_verify | ( | stp_vars_t * | v | ) |

Verify parameters.

Verify that the parameters selected are consistent with those allowed by the driver. This must be called prior to printing; failure to do so will result in printing failing.

Parameters

  v | the vars to use.

Returns
  0 on failure, 1 on success; other status values are reserved.

## stp_verify_parameter()

stp_parameter_verify_t stp_verify_parameter | ( | const stp_vars_t * | v,
|  | const char * | parameter,
|  | int | quiet
| ) |  |