Parameter Information

ParameterInfo

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.

ParameterType

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.

ParameterAccessMode

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.

ParameterInfo_dup

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

ParameterInfo_free

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

ParameterInfo_num_parameters

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

ParameterInfo_get_parameter_name

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

ParameterInfo_get_parameter_type

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

ParameterInfo_get_parameter_access_mode

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

ParameterInfo_get_parameter_display_name

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

ParameterInfo_get_parameter_effective_display_name

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

ParameterInfo_get_parameter_short_description

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

ParameterInfo_get_parameter_long_description

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

ParameterInfo_get_parameter_num_affected_parameters

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

ParameterInfo_get_parameter_affected_parameter_name

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

ParameterInfo_get_parameter_default_string

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

ParameterInfo_get_parameter_default_integer

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

ParameterInfo_get_parameter_default_float

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

ParameterInfo_get_parameter_default_boolean

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

ParameterInfo_get_parameter_unit

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

ParameterInfo_get_parameter_num_enumeration_entries

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

ParameterInfo_get_parameter_enumeration_entry_name

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

ParameterInfo_get_parameter_enumeration_entry_value

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:

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

ParameterInfo_get_parameter_enumeration_entry_display_name

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:

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

ParameterInfo_get_parameter_enumeration_entry_effective_display_name

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:

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

ParameterInfo_get_parameter_enumeration_entry_bn_value

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:

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

ParameterInfo_get_parameter_enumeration_entry_bn_display_name

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:

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

ParameterInfo_get_parameter_enumeration_entry_bn_effective_display_name

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:

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

ParameterInfo_get_parameter_integer_min

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

ParameterInfo_get_parameter_integer_max

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

ParameterInfo_get_parameter_integer_increment

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

ParameterInfo_get_parameter_float_min

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

ParameterInfo_get_parameter_float_max

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

ParameterInfo_get_parameter_float_increment

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

ParameterInfo_get_parameter_bn_type

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

ParameterInfo_get_parameter_bn_access_mode

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

ParameterInfo_get_parameter_bn_display_name

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

ParameterInfo_get_parameter_bn_effective_display_name

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

ParameterInfo_get_parameter_bn_short_description

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

ParameterInfo_get_parameter_bn_long_description

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

ParameterInfo_get_parameter_bn_num_affected_parameters

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

ParameterInfo_get_parameter_bn_affected_parameter_name

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

ParameterInfo_get_parameter_bn_default_string

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

ParameterInfo_get_parameter_bn_default_integer

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

ParameterInfo_get_parameter_bn_default_float

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

ParameterInfo_get_parameter_bn_default_boolean

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

ParameterInfo_get_parameter_bn_unit

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

ParameterInfo_get_parameter_bn_num_enumeration_entries

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

ParameterInfo_get_parameter_bn_enumeration_entry_name

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

ParameterInfo_get_parameter_bn_enumeration_entry_value

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:

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

ParameterInfo_get_parameter_bn_enumeration_entry_display_name

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:

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

ParameterInfo_get_parameter_bn_enumeration_entry_effective_display_name

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:

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

ParameterInfo_get_parameter_bn_enumeration_entry_bn_value

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:

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

ParameterInfo_get_parameter_bn_enumeration_entry_bn_display_name

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:

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

ParameterInfo_get_parameter_bn_enumeration_entry_bn_effective_display_name

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:

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

ParameterInfo_get_parameter_bn_integer_min

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

ParameterInfo_get_parameter_bn_integer_max

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

ParameterInfo_get_parameter_bn_integer_increment

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

ParameterInfo_get_parameter_bn_float_min

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

ParameterInfo_get_parameter_bn_float_max

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

ParameterInfo_get_parameter_bn_float_increment

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