Parameter Information

typedef struct fluxEngine_C_v1_ParameterInfo fluxEngine_C_v1_ParameterInfo

fluxEngine Parameter Information

This structure contains information about parameters that the user may use to influence behavior. Currently this is used in two places:

Connection parameters of devices. These cannot be explicitly set, but must be passed by the user as a list to fluxEngine_C_v1_DeviceGroup_connect(). These will typically include paths to calibration files that the user must provide.
Parameters that influence a device, such as the exposure time of a camera, the intensity of a light, etc.

Accessors to this structure provide information about the various parameters represented. There are no explicit functions to read or write parameter values, as these are highly context-dependent. For connection parameters there are no getters and setters, as the user must provide a list to the connect function. For device parameters there are various functions that will get or set a specific parameter value.

Note that in the case of device parameters this structure is dynamic - changing a device parameter might change the access mode of other parameters. See fluxEngine_C_v1_ParameterInfo_get_parameter_num_affected_parameters() and similar functions for details.

A note on the naming convention of accessors: whenever information is queried by index, there is typically also a function that queries by name. That function will have a _bn inserted into its signature and will take a name instead of the index. The only exception is the function that returns the actual name, which does not exist with a _bn variant, as that would just return itself.

enum fluxEngine_C_v1_ParameterType

The type of the parameter.

Values:

enumerator fluxEngine_C_v1_ParameterType_Unknown

Unknown type.

This is returned if a specific parameter does not fall into one of the other parameter types.

enumerator fluxEngine_C_v1_ParameterType_Boolean

Boolean.

The parameter can either be true or false.

enumerator fluxEngine_C_v1_ParameterType_Integer

Integer.

The parameter is an integer value. There may be additional limits imposed on the range of the integer value.

enumerator fluxEngine_C_v1_ParameterType_Float

Floating Point.

The parameter is a floating point value. There may be additional limits imposed on the range of the floating point value.

enumerator fluxEngine_C_v1_ParameterType_Enumeration

Enumeration.

The parameter can be chosen from a set of predetermined values. Each predetermined value is associated with an integer value as well as a unique name.

enumerator fluxEngine_C_v1_ParameterType_String

String.

The parameter is a string value. Note that strings have to be encoded as UTF-8.

enumerator fluxEngine_C_v1_ParameterType_File

File.

The parameter is the path to a file in the filesystem. The path can be accessed like a string.

Windows: as string-like parameters are always represented in UTF-8, the path here must also be encoded as UTF-8, not the local 8bit encoding. The UTF-8 representation will internally be converted to wide strings that will be used to access the actual file.

All other platforms: the local 8bit encoding should be used.

enumerator fluxEngine_C_v1_ParameterType_Command

Command.

A command parameter is a parmaeter that can be used to trigger an action on the device.

enum fluxEngine_C_v1_ParameterAccessMode

The access mode of a given parameter.

The access mode describes whether a parameter may be read from or written to.

Values:

enumerator fluxEngine_C_v1_ParameterAccessMode_NotAvailable

The parameter is not available.

This indicates that the parameter can currently neither be read nor written.

enumerator fluxEngine_C_v1_ParameterAccessMode_ReadOnly: The parameter is read-only.

enumerator fluxEngine_C_v1_ParameterAccessMode_WriteOnly

The parameter is write-only.

This is typically only the case for fluxEngine_C_v1_ParameterType_Command type parameters.

enumerator fluxEngine_C_v1_ParameterAccessMode_ReadWrite

The parameter may be read from and written to.

This is the case for most parameters.

int fluxEngine_C_v1_ParameterInfo_dup(fluxEngine_C_v1_ParameterInfo *pinfo, fluxEngine_C_v1_ParameterInfo **out, fluxEngine_C_v1_Error **error)

Duplicate a parameter information structure.

This will create a duplicate of the current structure. The duplicate structure will always return the same information as the original structure, even in the case that the structure represents dynamic device parameters.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters

pinfo – The structure to duplicate
out – [out] The resulting duplicate structure
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

void fluxEngine_C_v1_ParameterInfo_free(fluxEngine_C_v1_ParameterInfo *pinfo)

Free a parameter information structure.

This will release the memory associated with the parameter information structure. The structure must not be used after a call to this function. Passing NULL is allowed, in which case this function function has no effect.

Parameters

pinfo – The structure to free

int fluxEngine_C_v1_ParameterInfo_num_parameters(fluxEngine_C_v1_ParameterInfo *pinfo, fluxEngine_C_v1_Error **error)

Get the number of parameters in this parameter list.

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid

Parameters

pinfo – The parameter information structure to query
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

The number of parameters in this list on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char **name, fluxEngine_C_v1_Error **error)

Get the name of a parameter.

This will return the name of the parameter with the index index. A parameter’s name is an internal name that is used to uniquely identify the parameter. Please also take a look at the display name of a parameter when looking for something to display to the user.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
name – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_type(fluxEngine_C_v1_ParameterInfo *pinfo, int index, fluxEngine_C_v1_ParameterType *type, fluxEngine_C_v1_Error **error)

Get the type of a parameter.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_type().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
type – [out] The type of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_access_mode(fluxEngine_C_v1_ParameterInfo *pinfo, int index, fluxEngine_C_v1_ParameterAccessMode *access_mode, fluxEngine_C_v1_Error **error)

Get the access mode of a parameter.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_access_mode().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
access_mode – [out] The access mode of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char **display_name, fluxEngine_C_v1_Error **error)

Get the display name of the parameter.

If set a parameter’s display name is human-readable name that indicates that may be shown to the user and is likely more useful for a person than the internal name. This might not be set though (and then this method will return NULL). There is also a function fluxEngine_C_v1_ParameterInfo_get_parameter_effective_display_name() that returns the display name, or the internal name if the former is not set.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_display_name().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
display_name – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no specific display name has been set for this parameter.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_effective_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char **display_name, fluxEngine_C_v1_Error **error)

Get the effective display name of the parameter.

This will return the result of fluxEngine_C_v1_ParameterInfo_get_parameter_display_name(), unless that would be NULL, in which case the result of fluxEngine_C_v1_ParameterInfo_get_parameter_name() will be returned instead.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_effective_display_name().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
display_name – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_short_description(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char **description, fluxEngine_C_v1_Error **error)

Get the short description of a parameter.

This will often be used as a tooltip in GUIs. Not all parameters will have a short description, in which case the result of this function will be NULL.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_short_description().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
description – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no short description has been set for the parameter.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_long_description(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char **description, fluxEngine_C_v1_Error **error)

Get the long description of a parameter.

This may be a longer text that can span multiple lines. Not all parameters will have a short description, in which case the result of this function will be NULL.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_long_description().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
description – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no long description has been set for the parameter.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_num_affected_parameters(fluxEngine_C_v1_ParameterInfo *pinfo, int index, fluxEngine_C_v1_Error **error)

Get the number of parameters affected by changing this parameter.

When controlling devices certain parameters have an effect on other parameters. This could range from enabling or disabling the other parameter, changing the allowed range of the other parameter or even changing the value of the other parameter. For example, when changing the binning value of a camera device, the limits of the ROI are now also changed.

This function returns the number of parameters that are affected by the indicate parameter. For example: if there are three parameters in a device, "BinningHorziontal" (index 0), "OffsetX" (index 1) and "Width" (index 2), and changing the binning value would update both the "OffsetX" and "Width" parameters, then fluxEngine_C_v1_ParameterInfo_get_parameter_num_affected_parameters() would return 2 when index 0 is supplied, indicating that there are two parameters that are affected by the "BinningHorziontal" parameter.

It is possible that there are circulare references: a parameter A may affect a parameter B, which in turn might affect the parameter A again.

The list of affected parameters returned by fluxEngine’s public API will also cover indirect references: if a parameter A affects parameter B, and B itself affects C, then the list of affected parameters for A will include both B and C.

If a parameter A affects other parameters, the user should not rely on the other parameters having the same value, access mode and/or limits when A is changed, and should query that information again, if they require it.

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_num_affected_parameters().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

The number of parameters affected by the given parameter, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_affected_parameter_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int affected_index, char **affected_name, fluxEngine_C_v1_Error **error)

Get the name of an affected parameter.

Please see the documentation for fluxEngine_C_v1_ParameterInfo_get_parameter_num_affected_parameters() for further details on affected parmaeters.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_affected_parameter_name(). (The affecting parameter still has to be passed per index, as this function queries the name of the affected parameter.)

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterAffectedIndexOutOfRange

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
affected_index – The index of the affected parameter, must be from 0 to one less than the number of affected parameters.
affected_name – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_default_string(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char **value, fluxEngine_C_v1_Error **error)

Get the default value of a parameter as a string.

Connection parameters may have default values that can be queried. Note that device parameter do not have default values, and if this function is called for a parameter list of device parameters, the fluxEngine_C_v1_ErrorCode_ParameterNoDefaults error will be returned.

Except for Command parameters it is always possible to obtain a default value as a string, even if the parameter is not of string type:

In case of enumeration parameters the internal name of the enumeration entry will be returned.
In case of numeric parameters a string representation of that number will be returned.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_string().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterNoDefaults
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
value – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_default_integer(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int64_t *value, fluxEngine_C_v1_Error **error)

Get the default value of a parameter as an integer.

Connection parameters may have default values that can be queried. Note that device parameter do not have default values, and if this function is called for a parameter list of device parameters, the fluxEngine_C_v1_ErrorCode_ParameterNoDefaults error will be returned.

This will only work for integer and enumeration parameters. In the case of enumeration parameters the value of the default enumeration entry will be returned.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_integer().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterNoDefaults
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
value – [out] The default value of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_default_float(fluxEngine_C_v1_ParameterInfo *pinfo, int index, double *value, fluxEngine_C_v1_Error **error)

Get the default value of a parameter as a floating point value.

Connection parameters may have default values that can be queried. Note that device parameter do not have default values, and if this function is called for a parameter list of device parameters, the fluxEngine_C_v1_ErrorCode_ParameterNoDefaults error will be returned.

This will only work for floating point parameters.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_float().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterNoDefaults
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
value – [out] The default value of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_default_boolean(fluxEngine_C_v1_ParameterInfo *pinfo, int index, bool *value, fluxEngine_C_v1_Error **error)

Get the default value of a parameter as a boolean.

Connection parameters may have default values that can be queried. Note that device parameter do not have default values, and if this function is called for a parameter list of device parameters, the fluxEngine_C_v1_ErrorCode_ParameterNoDefaults error will be returned.

This will only work for boolean parameters.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_boolean().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterNoDefaults
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
value –
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_unit(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char **unit, fluxEngine_C_v1_Error **error)

Get a parameter’s unit.

Numeric parameters (integer and floating point) may have a unit associated with them, such as Hz or ms. This function will return the unit of the parameter as a string, or NULL if no unit has been set for the parameter.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_unit().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
unit – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be be set to NULL if the given parameter does not have a unit
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_num_enumeration_entries(fluxEngine_C_v1_ParameterInfo *pinfo, int index, fluxEngine_C_v1_Error **error)

Get the number of enumeration entries of this parameter.

If the supplied parameter is an enumeration parameter, this will return the number of entries in the enumeration.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_num_enumeration_entries().

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

The number of enumeration entries of the given enumeration parameter, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int entry_index, char **entry_name, fluxEngine_C_v1_Error **error)

Get the name of an enumeration entry.

For a given enumeration parameter and an index into the list of enumeration entries, return the name of that enumeration entry. The name of the entry will be unique within the enumeration, and, as with the parameter names, there will also be a display name for enumeration entries.

There is also a variant of this method that queries this information by the the parameter’s name (but not the entry’s name!), fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_name().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
entry_index – The index of the enumeration entry, starting at 0, ending at one less than the number of enumeration entries
entry_name – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_value(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int entry_index, int64_t *value, fluxEngine_C_v1_Error **error)

Get the value of an enumeration entry.

Return the integer value of a given enumeration entry.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_value(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_value(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_value(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_value(), specifying both the parameter and the enumeration entry by their names

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
entry_index – The index of the enumeration entry, starting at 0, ending at one less than the number of enumeration entries
value – [out] The value of the enumeration entry
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int entry_index, char **display_name, fluxEngine_C_v1_Error **error)

Get the display name of an enumeration entry.

Return the display name of a given enumeration entry. An enumeration entry may not have a display name set, in which case this function will return a NULL value.

There is also the method fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(), which will return the display name of the entry if set, otherwise the entry’s name.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_display_name(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_display_name(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_display_name(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_display_name(), specifying both the parameter and the enumeration entry by their names

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
entry_index – The index of the enumeration entry, starting at 0, ending at one less than the number of enumeration entries
display_name – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no specific display name has been set for the enumeration entry.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int entry_index, char **display_name, fluxEngine_C_v1_Error **error)

Get the effective display name of an enumeration entry.

Return the effective display name of a given enumeration entry, i.e. its display name if set, or its name otherwise.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_effective_display_name(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_effective_display_name(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_effective_display_name(), specifying both the parameter and the enumeration entry by their names

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
entry_index – The index of the enumeration entry, starting at 0, ending at one less than the number of enumeration entries
display_name – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_value(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char const *entry_name, int64_t *value, fluxEngine_C_v1_Error **error)

Get the value of an enumeration entry.

Return the integer value of a given enumeration entry.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_value(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_value(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_value(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_value(), specifying both the parameter and the enumeration entry by their names

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationNameDoesNotExist

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
entry_name – The name of the enumeration entry
value – [out] The value of the enumeration entry
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char const *entry_name, char **display_name, fluxEngine_C_v1_Error **error)

Get the display name of an enumeration entry.

Return the display name of a given enumeration entry. An enumeration entry may not have a display name set, in which case this function will return a NULL value.

There is also the method fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(), which will return the display name of the entry if set, otherwise the entry’s name.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_display_name(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_display_name(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_display_name(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_display_name(), specifying both the parameter and the enumeration entry by their names

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationNameDoesNotExist

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
entry_name – The name of the enumeration entry
display_name – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no specific display name has been set for the enumeration entry.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_effective_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char const *entry_name, char **display_name, fluxEngine_C_v1_Error **error)

Get the effective display name of an enumeration entry.

Return the effective display name of a given enumeration entry, i.e. its display name if set, or its name otherwise.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_effective_display_name(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_effective_display_name(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_effective_display_name(), specifying both the parameter and the enumeration entry by their names

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationNameDoesNotExist

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
entry_name – The name of the enumeration entry
display_name – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_integer_min(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int64_t *v, fluxEngine_C_v1_Error **error)

Get the lower limit of the integer parameter.

If an explicit limit is set on the given parameter this will return that limit. Otherwise the lowest value that a signed 64bit integer will be returned.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_integer_min().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
v – [out] The lower limit of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_integer_max(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int64_t *v, fluxEngine_C_v1_Error **error)

Get the upper limit of the integer parameter.

If an explicit limit is set on the given parameter this will return that limit. Otherwise the largest value that a signed 64bit integer will be returned.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_integer_max().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
v – [out] The upper limit of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_integer_increment(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int64_t *v, fluxEngine_C_v1_Error **error)

Get the increment of the integer parameter.

If an increment other than 1 is specified, this means that the valid values of the parameter are given by the formula min_value + increment * N, where N is a natural number.

If an explicit increment is set on the given parameter this will return that increment, and 1 otherwise.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_integer_increment().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
v – [out] The increment of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_float_min(fluxEngine_C_v1_ParameterInfo *pinfo, int index, double *v, fluxEngine_C_v1_Error **error)

Get the lower limit of the floating point parameter.

If an explicit limit is set on the given parameter this will return that limit. Otherwise the lowest finite value that a double precision floating point number can represent will be returned.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_float_min().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
v – [out] The lower limit of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_float_max(fluxEngine_C_v1_ParameterInfo *pinfo, int index, double *v, fluxEngine_C_v1_Error **error)

Get the upper limit of the floating point parameter.

If an explicit limit is set on the given parameter this will return that limit. Otherwise the largest finite value that a double precision floating point number can represent will be returned.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_float_max().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
v – [out] The upper limit of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_float_increment(fluxEngine_C_v1_ParameterInfo *pinfo, int index, double *v, fluxEngine_C_v1_Error **error)

Get the upper limit of the floating point parameter.

If an explicit increment is set on the given parameter this will return that increment, and 1 otherwise.

For floating point values the increment is more of a hint to the user (as compared to the integer case), as the actual value will be adjusted to the nearest allowed value once it is set.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_float_increment().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
index – The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
v – [out] The increment of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_type(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, fluxEngine_C_v1_ParameterType *type, fluxEngine_C_v1_Error **error)

Get the type of a parameter.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_type().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
type – [out] The type of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_access_mode(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, fluxEngine_C_v1_ParameterAccessMode *access_mode, fluxEngine_C_v1_Error **error)

Get the access mode of a parameter.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_access_mode().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
access_mode – [out] The access mode of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char **display_name, fluxEngine_C_v1_Error **error)

Get the display name of the parameter

If set a parameter’s display name is human-readable name that indicates that may be shown to the user and is likely more useful for a person than the internal name. This might not be set though (and then this method will return NULL). There is also a function fluxEngine_C_v1_ParameterInfo_get_parameter_effective_display_name() that returns the display name, or the internal name if the former is not set.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_display_name().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
display_name – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no specific display name has been set for this parameter.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_effective_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char **display_name, fluxEngine_C_v1_Error **error)

Get the effective display name of the parameter.

This will return the result of fluxEngine_C_v1_ParameterInfo_get_parameter_display_name(), unless that would be NULL, in which case the result of fluxEngine_C_v1_ParameterInfo_get_parameter_name() will be returned instead.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_effective_display_name().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
display_name – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_short_description(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char **description, fluxEngine_C_v1_Error **error)

Get the short description of a parameter.

This will often be used as a tooltip in GUIs. Not all parameters will have a short description, in which case the result of this function will be NULL.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_short_description().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
description – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no short description has been set for the parameter.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_long_description(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char **description, fluxEngine_C_v1_Error **error)

Get the long description of a parameter.

This may be a longer text that can span multiple lines. Not all parameters will have a short description, in which case the result of this function will be NULL.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_long_description().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
description – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no long description has been set for the parameter.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_num_affected_parameters(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, fluxEngine_C_v1_Error **error)

Get the number of parameters affected by changing this parameter.

When controlling devices certain parameters have an effect on other parameters. This could range from enabling or disabling the other parameter, changing the allowed range of the other parameter or even changing the value of the other parameter. For example, when changing the binning value of a camera device, the limits of the ROI are now also changed.

This function returns the number of parameters that are affected by the indicate parameter. For example: if there are three parameters in a device, "BinningHorziontal" (index 0), "OffsetX" (index 1) and "Width" (index 2), and changing the binning value would update both the "OffsetX" and "Width" parameters, then fluxEngine_C_v1_ParameterInfo_get_parameter_num_affected_parameters() would return 2 when index 0 is supplied, indicating that there are two parameters that are affected by the "BinningHorziontal" parameter.

It is possible that there are circulare references: a parameter A may affect a parameter B, which in turn might affect the parameter A again.

The list of affected parameters returned by fluxEngine’s public API will also cover indirect references: if a parameter A affects parameter B, and B itself affects C, then the list of affected parameters for A will include both B and C.

If a parameter A affects other parameters, the user should not rely on the other parameters having the same value, access mode and/or limits when A is changed, and should query that information again, if they require it.

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_num_affected_parameters().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

The number of parameters affected by the given parameter, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_affected_parameter_name(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int affected_index, char **affected_name, fluxEngine_C_v1_Error **error)

Get the name of an affected parameter.

Please see the documentation for fluxEngine_C_v1_ParameterInfo_get_parameter_bn_num_affected_parameters() for further details on affected parmaeters.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_affected_parameter_name().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterAffectedIndexOutOfRange

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
affected_index – The index of the affected parameter, must be from 0 to one less than the number of affected parameters.
affected_name – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_string(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char **value, fluxEngine_C_v1_Error **error)

Get the default value of a parameter as a string.

Connection parameters may have default values that can be queried. Note that device parameter do not have default values, and if this function is called for a parameter list of device parameters, the fluxEngine_C_v1_ErrorCode_ParameterNoDefaults error will be returned.

Except for Command parameters it is always possible to obtain a default value as a string, even if the parameter is not of string type:

In case of enumeration parameters the internal name of the enumeration entry will be returned.
In case of numeric parameters a string representation of that number will be returned.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_default_string().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterNoDefaults
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
value – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_integer(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int64_t *value, fluxEngine_C_v1_Error **error)

Get the default value of a parameter as an integer.

Connection parameters may have default values that can be queried. Note that device parameter do not have default values, and if this function is called for a parameter list of device parameters, the fluxEngine_C_v1_ErrorCode_ParameterNoDefaults error will be returned.

This will only work for integer and enumeration parameters. In the case of enumeration parameters the value of the default enumeration entry will be returned.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_default_integer().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterNoDefaults
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
value – [out] The default value of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_float(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, double *value, fluxEngine_C_v1_Error **error)

Get the default value of a parameter as a floating point value.

Connection parameters may have default values that can be queried. Note that device parameter do not have default values, and if this function is called for a parameter list of device parameters, the fluxEngine_C_v1_ErrorCode_ParameterNoDefaults error will be returned.

This will only work for floating point parameters.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_default_float().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterNoDefaults
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
value – [out] The default value of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_boolean(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, bool *value, fluxEngine_C_v1_Error **error)

Get the default value of a parameter as a boolean.

Connection parameters may have default values that can be queried. Note that device parameter do not have default values, and if this function is called for a parameter list of device parameters, the fluxEngine_C_v1_ErrorCode_ParameterNoDefaults error will be returned.

This will only work for boolean parameters.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_default_boolean().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterNoDefaults
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
value – [out] The default value of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_unit(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char **unit, fluxEngine_C_v1_Error **error)

Get a parameter’s unit.

Numeric parameters (integer and floating point) may have a unit associated with them, such as Hz or ms. This function will return the unit of the parameter as a string, or NULL if no unit has been set for the parameter.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_default_unit().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
unit – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be be set to NULL if the given parameter does not have a unit
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_num_enumeration_entries(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, fluxEngine_C_v1_Error **error)

Get the number of enumeration entries of this parameter.

If the supplied parameter is an enumeration parameter, this will return the number of entries in the enumeration.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_num_enumeration_entries().

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

The number of enumeration entries of the given enumeration parameter, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_name(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int entry_index, char **entry_name, fluxEngine_C_v1_Error **error)

Get the name of an enumeration entry.

For a given enumeration parameter and an index into the list of enumeration entries, return the name of that enumeration entry. The name of the entry will be unique within the enumeration, and, as with the parameter names, there will also be a display name for enumeration entries.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_name().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
entry_index – The index of the enumeration entry, starting at 0, ending at one less than the number of enumeration entries
entry_name – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_value(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int entry_index, int64_t *value, fluxEngine_C_v1_Error **error)

Get the value of an enumeration entry.

Return the integer value of a given enumeration entry.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_value(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_value(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_value(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_value(), specifying both the parameter and the enumeration entry by their names

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
entry_index – The index of the enumeration entry, starting at 0, ending at one less than the number of enumeration entries
value – [out] The value of the enumeration entry
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int entry_index, char **display_name, fluxEngine_C_v1_Error **error)

Get the display name of an enumeration entry.

Return the display name of a given enumeration entry. An enumeration entry may not have a display name set, in which case this function will return a NULL value.

There is also the method fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(), which will return the display name of the entry if set, otherwise the entry’s name.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_display_name(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_display_name(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_display_name(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_display_name(), specifying both the parameter and the enumeration entry by their names

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
entry_index – The index of the enumeration entry, starting at 0, ending at one less than the number of enumeration entries
display_name – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no specific display name has been set for the enumeration entry.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_effective_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int entry_index, char **display_name, fluxEngine_C_v1_Error **error)

Get the effective display name of an enumeration entry.

Return the effective display name of a given enumeration entry, i.e. its display name if set, or its name otherwise.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_effective_display_name(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_effective_display_name(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_effective_display_name(), specifying both the parameter and the enumeration entry by their names

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
entry_index – The index of the enumeration entry, starting at 0, ending at one less than the number of enumeration entries
display_name – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_value(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char const *entry_name, int64_t *value, fluxEngine_C_v1_Error **error)

Get the value of an enumeration entry.

Return the integer value of a given enumeration entry.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_value(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_value(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_value(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_value(), specifying both the parameter and the enumeration entry by their names

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationNameDoesNotExist

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
entry_name – The name of the enumeration entry
value – [out] The value of the enumeration entry
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char const *entry_name, char **display_name, fluxEngine_C_v1_Error **error)

Get the display name of an enumeration entry.

Return the display name of a given enumeration entry. An enumeration entry may not have a display name set, in which case this function will return a NULL value.

There is also the method fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(), which will return the display name of the entry if set, otherwise the entry’s name.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_display_name(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_display_name(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_display_name(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_display_name(), specifying both the parameter and the enumeration entry by their names

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationNameDoesNotExist

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
entry_name – The name of the enumeration entry
display_name – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no specific display name has been set for the enumeration entry.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_effective_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char const *entry_name, char **display_name, fluxEngine_C_v1_Error **error)

Get the effective display name of an enumeration entry.

Return the effective display name of a given enumeration entry, i.e. its display name if set, or its name otherwise.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_effective_display_name(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_effective_display_name(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_effective_display_name(), specifying both the parameter and the enumeration entry by their names

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationNameDoesNotExist

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
entry_name – The name of the enumeration entry
display_name – [out] The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_integer_min(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int64_t *v, fluxEngine_C_v1_Error **error)

Get the lower limit of the integer parameter.

If an explicit limit is set on the given parameter this will return that limit. Otherwise the lowest value that a signed 64bit integer will be returned.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_integer_min().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
v – [out] The lower limit of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_integer_max(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int64_t *v, fluxEngine_C_v1_Error **error)

Get the upper limit of the integer parameter.

If an explicit limit is set on the given parameter this will return that limit. Otherwise the largest value that a signed 64bit integer will be returned.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_integer_max().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
v – [out] The upper limit of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_integer_increment(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int64_t *v, fluxEngine_C_v1_Error **error)

Get the increment of the integer parameter.

If an increment other than 1 is specified, this means that the valid values of the parameter are given by the formula min_value + increment * N, where N is a natural number.

If an explicit increment is set on the given parameter this will return that increment, and 1 otherwise.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_integer_increment().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
v – [out] The increment of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_float_min(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, double *v, fluxEngine_C_v1_Error **error)

Get the lower limit of the floating point parameter.

If an explicit limit is set on the given parameter this will return that limit. Otherwise the lowest finite value that a double precision floating point number can represent will be returned.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_float_min().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
v – [out] The lower limit of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_float_max(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, double *v, fluxEngine_C_v1_Error **error)

Get the upper limit of the floating point parameter.

If an explicit limit is set on the given parameter this will return that limit. Otherwise the largest finite value that a double precision floating point number can represent will be returned.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_float_max().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
v – [out] The upper limit of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_float_increment(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, double *v, fluxEngine_C_v1_Error **error)

Get the upper limit of the floating point parameter.

If an explicit increment is set on the given parameter this will return that increment, and 1 otherwise.

For floating point values the increment is more of a hint to the user (as compared to the integer case), as the actual value will be adjusted to the nearest allowed value once it is set.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_float_increment().

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Parameters

pinfo – The parameter information structure to query
name – The name of the parameter to query
v – [out] The increment of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure