Parameter Information

ParameterInfo

class ParameterInfo

Parameter information / list.

This class contains information about available parameters that may be updated by the user. It is used in two places:

  • During device connection this describes the available connection parameters. The user must provide a string -> string map with the values of these parameters during the connection process.

  • When connected to a device this describes the parameters the device provides. Getting/setting parameters occurs via separate methods of the Device class though.

Accessor methods of this class provide information about the various parameters represented. There are no explicit method sto 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 methods 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 ParameterInfo::affectedParameters() for details.

Each accessor is available in both an indexed variant, as well as a named variant (except for the accessor that obtains the name itself), depending on the type of the argument. For example, one may call ParameterInfo::parameterAccessMode() with an integer parameter, specifying an index into the list of parameters, starting at 0, ending at one less of the parameter count. But one may also provide the name of the parameter as a string argument to that method, to obtain the access mode of that parameter by name.

Additionally there is also the ParameterInfo::parameter() method, which returns a ParameterInfo::Parameter structure. That structure contains all the information about a specific parameter at once, and doesn’t require the user to obtain information about parameters one accessor at a time. If only a specific piece of information is required, though, it may be more efficient to simply ask for that specific piece of information directly via an accessor. Note that this method is only available if the compiler and the standard library support C++17, as std::variant and std::optional are used extensively in this structure.

For reading parameter information that optionally may contain a string value, such as the display name, or the short and long descriptions, there are two types of accessors:

  • C++11 compatible accessors whose method name starts with a get. They return a boolean value to indicate whether the value was present, and take a reference argument where the result will be stored if the value was present. (If the value was not present the second argument will remain untouched.)

  • C++17 accessors that rely on std::optional that return a std::optional<std::string> that don’t contain a get prefix in their name.

Public Types

enum class Type

The type of the parameter.

Values:

enumerator Unknown

Unknown type.

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

enumerator Boolean

Boolean.

The parameter can either be true or false.

enumerator Integer

Integer.

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

enumerator 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 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 String

String.

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

enumerator 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 Command

Command.

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

enum class AccessMode

The access mode of a given parameter.

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

Values:

enumerator NotAvailable

The parameter is not available.

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

enumerator ReadOnly

The parameter is read-only.

enumerator WriteOnly

The parameter is write-only.

This is typically only the case for ParameterInfo::Type::Command type parameters.

enumerator ReadWrite

The parameter may be read from and written to.

This is the case for most parameters.

Public Functions

ParameterInfo() = default

Default constructor.

Calling accessors to a default-initialized structure will result in an exception being thrown.

inline ParameterInfo(ParameterInfo const &other)

Copy constructor.

If an error occurs, an exception will be thrown. The following exceptions may occur:

  • std::bad_alloc

  • std::invalid_argument

  • Error

Parameters:

other – The object to copy

inline ParameterInfo(ParameterInfo &&other) noexcept

Move constructor.

Parameters:

other – The object to move

inline ParameterInfo &operator=(ParameterInfo const &other)

Copy assignment operator.

If an error occurs, an exception will be thrown. The following exceptions may occur:

  • std::bad_alloc

  • std::invalid_argument

  • Error

Parameters:

other – The object to copy

Returns:

A reference to *this

inline ParameterInfo &operator=(ParameterInfo &&other) noexcept

Move assignment operator.

Parameters:

other – The object to move

Returns:

A reference to *this

inline ~ParameterInfo() noexcept

Destructor.

inline std::size_t parameterCount() const

Get the number of parameters.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Returns:

The number of parameters

inline std::vector<std::string> parameterNames() const

Get the list of parameter names.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Returns:

The list of parameter names

inline Parameter parameter(std::size_t n) const

Get all information about a specific parameter by index.

If a parameter with that index does not exist, an error will be thrown.

This requires C++17 support for std::optional and std::variant.

If an error occurs, an exception will be thrown. The following exceptions may occur:

See also

ParameterInfo::Parameter

Parameters:

n – The index of the parameter, must be at most one smaller than the result of parameterCount().

Returns:

The full information about a specific parameter.

inline Parameter parameter(std::string const &name) const

Get all information about a specific parameter by name.

If a parameter with that name does not exist, and error will be thrown.

This requires C++17 support for std::optional and std::variant.

If an error occurs, an exception will be thrown. The following exceptions may occur:

See also

ParameterInfo::Parameter

Parameters:

name – The name of the parameter

Returns:

The full information about a specific parameter.

inline std::vector<Parameter> parameters() const

Get a list of all parameters.

This requires C++17 support for std::optional and std::variant.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Returns:

A list of all parameters

inline Type parameterType(std::size_t i) const

Get the type of the parameter by index.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

i – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The type of the parameter

inline Type parameterType(std::string const &name) const

Get the type of the parameter by name.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

name – The name of the parameter

Returns:

The type of the parameter

inline AccessMode parameterAccessMode(std::size_t i) const

Get the access mode of the parameter by index.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

i – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The access mode of the parameter

inline AccessMode parameterAccessMode(std::string const &name) const

Get the access mode of the parameter by name.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

name – The name of the parameter

Returns:

The access mode of the parameter

inline bool getParameterDisplayName(std::size_t i, std::string &result) const

Get the display name of the parameter by index.

A display name is an optional more human-readable name of a parameter.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • i – The index of the parameter, must be at most one less than the value returned by parameterCount().

  • result – [out] Where to store the result. This will only be touched if this method returns true.

Returns:

true if a display name was set for the parameter (with the result argument being updated to that value), false otherwise.

inline bool getParameterDisplayName(std::string const &name, std::string &result) const

Get the display name of the parameter by name.

A display name is an optional more human-readable name of a parameter.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • name – The name of the parameter

  • result – [out] Where to store the result. This will only be touched if this method returns true.

Returns:

true if a display name was set for the parameter (with the result argument being updated to that value), false otherwise.

inline std::string parameterEffectiveDisplayName(std::size_t i) const

Get the effective display name of a parameter by index.

This will return the parameter’s display name, if set, or otherwise the parameter’s name. This is a convenient accessor to always obtain a name that may be shown to the user, but that will show a more human-readable name if possible.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

i – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The effective display name of a parameter

inline std::string parameterEffectiveDisplayName(std::string const &name) const

Get the effective display name of a parameter by name.

This will return the parameter’s display name, if set, or otherwise the parameter’s name. This is a convenient accessor to always obtain a name that may be shown to the user, but that will show a more human-readable name if possible.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

name – The name of the parameter

Returns:

The effective display name of a parameter

inline bool getParameterShortDescription(std::size_t i, std::string &result) const

Get the short description of the parameter by index.

If set a short description is often displayed in form of a tool-tip to the user.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::parameterShortDescription().

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • i – The index of the parameter, must be at most one less than the value returned by parameterCount().

  • result – [out] Where to store the result. This will only be touched if this method returns true.

Returns:

true if a short description was set for the parameter (with the result argument being updated to that value), false otherwise.

inline bool getParameterShortDescription(std::string const &name, std::string &result) const

Get the short description of the parameter by name.

If set a short description is often displayed in form of a tool-tip to the user.

If an error occurs, an exception will be thrown. The following exceptions may occur:

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::parameterShortDescription().

Parameters:

  • name – The name of the parameter

  • result – [out] Where to store the result. This will only be touched if this method returns true.

Returns:

true if a short description was set for the parameter (with the result argument being updated to that value), false otherwise.

inline bool getParameterLongDescription(std::size_t i, std::string &result) const

Get the long description of the parameter by index.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::parameterLongDescription().

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • i – The index of the parameter, must be at most one less than the value returned by parameterCount().

  • result – [out] Where to store the result. This will only be touched if this method returns true.

Returns:

true if a long description was set for the parameter (with the result argument being updated to that value), false otherwise.

inline bool getParameterLongDescription(std::string const &name, std::string &result) const

Get the long description of the parameter by name.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::parameterLongDescription().

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • name – The name of the parameter

  • result – [out] Where to store the result. This will only be touched if this method returns true.

Returns:

true if a long description was set for the parameter (with the result argument being updated to that value), false otherwise.

inline bool getParameterUnit(std::size_t i, std::string &result) const

Get the unit of the parameter by index.

Numeric parameters (ParameterInfo::Type::Integer and ParameterInfo::Type::Float) may have a unit assigned to them that describes the physical unit of the parameter, such as “ms” or “Hz.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::parameterUnit().

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • i – The index of the parameter, must be at most one less than the value returned by parameterCount().

  • result – [out] Where to store the result. This will only be touched if this method returns true.

Returns:

true if a long description was set for the parameter (with the result argument being updated to that value), false otherwise.

inline bool getParameterUnit(std::string const &name, std::string &result) const

Get the unit of the parameter by name.

Numeric parameters (ParameterInfo::Type::Integer and ParameterInfo::Type::Float) may have a unit assigned to them that describes the physical unit of the parameter, such as “ms” or “Hz.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::parameterUnit().

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • name – The name of the parameter

  • result – [out] Where to store the result. This will only be touched if this method returns true.

Returns:

true if a long description was set for the parameter (with the result argument being updated to that value), false otherwise.

inline std::optional<std::string> parameterDisplayName(std::size_t i) const

Get a parameter’s display name by index.

A display name is an optional more human-readable name of a parameter.

This accessor is only available with a C++17 compiler that supports std::optional. For compilers without such aupport, please take a look at the ParameterInfo::getParameterDisplayName() method.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

i – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The parameter’s display name, or std::nullopt if that is not set.

inline std::optional<std::string> parameterDisplayName(std::string const &name) const

Get a parameter’s display name by name.

A display name is an optional more human-readable name of a parameter.

This accessor is only available with a C++17 compiler that supports std::optional. For compilers without such aupport, please take a look at the ParameterInfo::getParameterDisplayName() method.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

name – The name of the parameter

Returns:

The parameter’s display name, or std::nullopt if that is not set.

inline std::optional<std::string> parameterShortDescription(std::size_t i) const

Get a parameter’s short description by index.

If set a short description is often displayed in form of a tool-tip to the user.

This accessor is only available with a C++17 compiler that supports std::optional. For compilers without such aupport, please take a look at the ParameterInfo::getParameterShortDescription() method.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

i – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The parameter’s short description, or std::nullopt if that is not set.

inline std::optional<std::string> parameterShortDescription(std::string const &name) const

Get a parameter’s short description by name.

If set a short description is often displayed in form of a tool-tip to the user.

This accessor is only available with a C++17 compiler that supports std::optional. For compilers without such aupport, please take a look at the ParameterInfo::getParameterShortDescription() method.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

name – The name of the parameter

Returns:

The parameter’s short description, or std::nullopt if that is not set.

inline std::optional<std::string> parameterLongDescription(std::size_t i) const

Get a parameter’s long description by index.

This accessor is only available with a C++17 compiler that supports std::optional. For compilers without such aupport, please take a look at the ParameterInfo::getParameterLongDescription() method.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

i – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The parameter’s long description, or std::nullopt if that is not set.

inline std::optional<std::string> parameterLongDescription(std::string const &name) const

Get a parameter’s long description by name.

If set a short description is often displayed in form of a tool-tip to the user.

This accessor is only available with a C++17 compiler that supports std::optional. For compilers without such aupport, please take a look at the ParameterInfo::getParameterLongDescription() method.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

name – The name of the parameter

Returns:

The parameter’s long description, or std::nullopt if that is not set.

inline std::optional<std::string> parameterUnit(std::size_t i) const

Get a parameter’s unit by index.

Numeric parameters (ParameterInfo::Type::Integer and ParameterInfo::Type::Float) may have a unit assigned to them that describes the physical unit of the parameter, such as “ms” or “Hz.

This accessor is only available with a C++17 compiler that supports std::optional. For compilers without such aupport, please take a look at the ParameterInfo::getParameterUnit() method.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

i – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The parameter’s unit, or std::nullopt if that is not set.

inline std::optional<std::string> parameterUnit(std::string const &name) const

Get a parameter’s unit by name.

Numeric parameters (ParameterInfo::Type::Integer and ParameterInfo::Type::Float) may have a unit assigned to them that describes the physical unit of the parameter, such as “ms” or “Hz.

This accessor is only available with a C++17 compiler that supports std::optional. For compilers without such aupport, please take a look at the ParameterInfo::getParameterUnit() method.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

name – The name of the parameter

Returns:

The parameter’s unit, or std::nullopt if that is not set.

inline std::vector<std::string> affectedParameters(std::size_t i) const

Get the parameters affected by changes to a given parameter (by index)

Given the index of a parameter, determine the list of parameters that might change if the value of the chosen parameter changes. For example, when changing the BinningHorizontal parameter of a camera, the value and limits of the OffsetX and Width parameters of that camera may change as a result of the change in binning. The parameters that may be affected by a change in parameter values are listed here.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

i – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The names of the parameters that may be affected by changes to the value of the specified parameter.

inline std::vector<std::string> affectedParameters(std::string const &name) const

Get the parameters affected by a given parameter (by name)

Given the name of a parameter, determine the list of parameters that might change if the value of the chosen parameter changes. For example, when changing the BinningHorizontal parameter of a camera, the value and limits of the OffsetX and Width parameters of that camera may change as a result of the change in binning. The parameters that may be affected by a change in parameter values are listed here.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

name – The name of the parameter

Returns:

The names of the parameters that may be affected by changes to the value of the specified parameter.

inline std::string parameterDefaultStringValue(std::size_t i) const

Get the default value of a parameter (string type, by index)

For parameters of ParameterInfo::Type::String or ParameterInfo::Type::File type obtain the default value of the parameter. The default value of a string-like parameter may be an empty string.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that &#8212; though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.) In that case this method will throw an error.

For parameters describing how to connect to a specific device there may be a default value, and that will be returned by this method.

If the parameter is not of the correct type an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

i – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The default value of the parameter

inline std::string parameterDefaultStringValue(std::string const &name) const

Get the default value of a parameter (string type, by name)

For parameters of ParameterInfo::Type::String or ParameterInfo::Type::File type obtain the default value of the parameter. The default value of a string-like parameter may be an empty string.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that &#8212; though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.) In that case this method will throw an error.

For parameters describing how to connect to a specific device there may be a default value, and that will be returned by this method.

If the parameter is not of the correct type an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

name – The name of the parameter

Returns:

The default value of the parameter

inline int64_t parameterDefaultIntegerValue(std::size_t i) const

Get the default value of a parameter (integer type, by index)

For parameters of ParameterInfo::Type::Integer or ParameterInfo::Type::Enumeration type obtain the default value of the parameter.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that &#8212; though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.) In that case this method will throw an error.

For parameters describing how to connect to a specific device there may be a default value, and that will be returned by this method.

If the parameter is not of the correct type an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

i – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The default value of the parameter

inline int64_t parameterDefaultIntegerValue(std::string const &name) const

Get the default value of a parameter (integer type, by name)

For parameters of ParameterInfo::Type::Integer or ParameterInfo::Type::Enumeration type obtain the default value of the parameter.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that &#8212; though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.) In that case this method will throw an error.

For parameters describing how to connect to a specific device there may be a default value, and that will be returned by this method.

If the parameter is not of the correct type an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

name – The name of the parameter

Returns:

The default value of the parameter

inline double parameterDefaultFloatValue(std::size_t i) const

Get the default value of a parameter (float type, by index)

For parameters of ParameterInfo::Type::Float type obtain the default value of the parameter.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that &#8212; though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.) In that case this method will throw an error.

For parameters describing how to connect to a specific device there may be a default value, and that will be returned by this method.

If the parameter is not of the correct type an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

i – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The default value of the parameter

inline double parameterDefaultFloatValue(std::string const &name) const

Get the default value of a parameter (float type, by name)

For parameters of ParameterInfo::Type::Float type obtain the default value of the parameter.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that &#8212; though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.) In that case this method will throw an error.

For parameters describing how to connect to a specific device there may be a default value, and that will be returned by this method.

If the parameter is not of the correct type an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

name – The name of the parameter

Returns:

The default value of the parameter

inline bool parameterDefaultBooleanValue(std::size_t i) const

Get the default value of a parameter (bool type, by index)

For parameters of ParameterInfo::Type::Boolean type obtain the default value of the parameter.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that &#8212; though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.) In that case this method will throw an error.

For parameters describing how to connect to a specific device there may be a default value, and that will be returned by this method.

If the parameter is not of the correct type an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

i – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The default value of the parameter

inline bool parameterDefaultBooleanValue(std::string const &name) const

Get the default value of a parameter (bool type, by name)

For parameters of ParameterInfo::Type::Boolean type obtain the default value of the parameter.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that &#8212; though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.) In that case this method will throw an error.

For parameters describing how to connect to a specific device there may be a default value, and that will be returned by this method.

If the parameter is not of the correct type an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

name – The name of the parameter

Returns:

The default value of the parameter

inline std::vector<std::string> enumerationEntryNames(std::size_t i) const

Get the names of all enumeration entries of an enumeration parameter (parameter by index)

For a parameter of type ParameterInfo::Type::Enumeration return a list of the names of all enumeration entries of that parameter.

If the parameter is not of enumeration type, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

i – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The enumeration entries of the parameter

inline std::vector<std::string> enumerationEntryNames(std::string const &name) const

Get the names of all enumeration entries of an enumeration parameter (parameter by name)

For a parameter of type ParameterInfo::Type::Enumeration return a list of the names of all enumeration entries of that parameter.

If the parameter is not of enumeration type, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

name – The name of the parameter

Returns:

The enumeration entries of the parameter

inline int64_t enumerationEntryValue(std::size_t parameterIndex, std::size_t entryIndex) const

Get the value of an enumeration entry of an enumeration parameter (parameter by index, entry by index)

For a parameter of type ParameterInfo::Type::Enumeration return the value of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • parameterIndex – The index of the parameter, must be at most one less than the value returned by parameterCount().

  • entryIndex – The index of the entry, must be at most one less than the size of the vector returned by enumerationEntryNames().

Returns:

The value of the enumeration entry

inline int64_t enumerationEntryValue(std::size_t parameterIndex, std::string const &entryName) const

Get the value of an enumeration entry of an enumeration parameter (parameter by index, entry by name)

For a parameter of type ParameterInfo::Type::Enumeration return the value of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • parameterIndex – The index of the parameter, must be at most one less than the value returned by parameterCount().

  • entryName – The name of the enumeration entry

Returns:

The value of the enumeration entry

inline int64_t enumerationEntryValue(std::string const &parameterName, std::size_t entryIndex) const

Get the value of an enumeration entry of an enumeration parameter (parameter by name, entry by index)

For a parameter of type ParameterInfo::Type::Enumeration return the value of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • parameterName – The name of the parameter

  • entryIndex – The index of the entry, must be at most one less than the size of the vector returned by enumerationEntryNames().

Returns:

The value of the enumeration entry

inline int64_t enumerationEntryValue(std::string const &parameterName, std::string const &entryName) const

Get the value of an enumeration entry of an enumeration parameter (parameter by name, entry by name)

For a parameter of type ParameterInfo::Type::Enumeration return the value of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • parameterName – The name of the parameter

  • entryName – The name of the enumeration entry

Returns:

The value of the enumeration entry

inline bool getEnumerationEntryDisplayName(std::size_t parameterIndex, std::size_t entryIndex, std::string &result) const

Get the display name of an enumeration entry of an enumeration parameter (parameter by index, entry by index)

For a parameter of type ParameterInfo::Type::Enumeration return the display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::enumerationEntryDisplayName().

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • parameterIndex – The index of the parameter, must be at most one less than the value returned by parameterCount().

  • entryIndex – The index of the entry, must be at most one less than the size of the vector returned by enumerationEntryNames().

  • result – [out] Where to store the result. This will only be touched if this method returns true.

Returns:

true if a display name was set for the enumeration entry (with the result argument being updated to that value), false otherwise.

inline bool getEnumerationEntryDisplayName(std::size_t parameterIndex, std::string const &entryName, std::string &result) const

Get the display name of an enumeration entry of an enumeration parameter (parameter by index, entry by name)

For a parameter of type ParameterInfo::Type::Enumeration return the display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::enumerationEntryDisplayName().

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • parameterIndex – The index of the parameter, must be at most one less than the value returned by parameterCount().

  • entryName – The name of the enumeration entry

  • result – [out] Where to store the result. This will only be touched if this method returns true.

Returns:

true if a display name was set for the enumeration entry (with the result argument being updated to that value), false otherwise.

inline bool getEnumerationEntryDisplayName(std::string const &parameterName, std::size_t entryIndex, std::string &result) const

Get the display name of an enumeration entry of an enumeration parameter (parameter by name, entry by index)

For a parameter of type ParameterInfo::Type::Enumeration return the display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::enumerationEntryDisplayName().

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • parameterName – The name of the parameter

  • entryIndex – The index of the entry, must be at most one less than the size of the vector returned by enumerationEntryNames().

  • result – [out] Where to store the result. This will only be touched if this method returns true.

Returns:

true if a display name was set for the enumeration entry (with the result argument being updated to that value), false otherwise.

inline bool getEnumerationEntryDisplayName(std::string const &parameterName, std::string const &entryName, std::string &result) const

Get the display name of an enumeration entry of an enumeration parameter (parameter by name, entry by name)

For a parameter of type ParameterInfo::Type::Enumeration return the display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::enumerationEntryDisplayName().

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • parameterName – The name of the parameter

  • entryName – The name of the enumeration entry

  • result – [out] Where to store the result. This will only be touched if this method returns true.

Returns:

true if a display name was set for the enumeration entry (with the result argument being updated to that value), false otherwise.

inline std::optional<std::string> enumerationEntryDisplayName(std::size_t parameterIndex, std::size_t entryIndex) const

Get the display name of an enumeration entry of an enumeration parameter (parameter by index, entry by index)

For a parameter of type ParameterInfo::Type::Enumeration return the display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a version of this method that doesn’t require support for std::optional, ParameterInfo::getEnumerationEntryDisplayName().

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • parameterIndex – The index of the parameter, must be at most one less than the value returned by parameterCount().

  • entryIndex – The index of the entry, must be at most one less than the size of the vector returned by enumerationEntryNames().

Returns:

The display name of the enumeration entry if set, or otherwise std::nullopt.

inline std::optional<std::string> enumerationEntryDisplayName(std::size_t parameterIndex, std::string const &entryName) const

Get the display name of an enumeration entry of an enumeration parameter (parameter by index, entry by name)

For a parameter of type ParameterInfo::Type::Enumeration return the display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a version of this method that doesn’t require support for std::optional, ParameterInfo::getEnumerationEntryDisplayName().

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • parameterIndex – The index of the parameter, must be at most one less than the value returned by parameterCount().

  • entryName – The name of the enumeration entry

Returns:

The display name of the enumeration entry if set, or otherwise std::nullopt.

inline std::optional<std::string> enumerationEntryDisplayName(std::string const &parameterName, std::size_t entryIndex) const

Get the display name of an enumeration entry of an enumeration parameter (parameter by name, entry by index)

For a parameter of type ParameterInfo::Type::Enumeration return the display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a version of this method that doesn’t require support for std::optional, ParameterInfo::getEnumerationEntryDisplayName().

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • parameterName – The name of the parameter

  • entryIndex – The index of the entry, must be at most one less than the size of the vector returned by enumerationEntryNames().

Returns:

The display name of the enumeration entry if set, or otherwise std::nullopt.

inline std::optional<std::string> enumerationEntryDisplayName(std::string const &parameterName, std::string const &entryName) const

Get the display name of an enumeration entry of an enumeration parameter (parameter by name, entry by name)

For a parameter of type ParameterInfo::Type::Enumeration return the display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a version of this method that doesn’t require support for std::optional, ParameterInfo::getEnumerationEntryDisplayName().

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • parameterName – The name of the parameter

  • entryName – The name of the enumeration entry

Returns:

The display name of the enumeration entry if set, or otherwise std::nullopt.

inline std::string enumerationEntryEffectiveDisplayName(std::size_t parameterIndex, std::size_t entryIndex) const

Get the effective display name of an enumeration entry of an enumeration parameter (parameter by index, entry by index)

For a parameter of type ParameterInfo::Type::Enumeration return the effective display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a version of this method that doesn’t require support for std::optional, ParameterInfo::getEnumerationEntryDisplayName().

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • parameterIndex – The index of the parameter, must be at most one less than the value returned by parameterCount().

  • entryIndex – The index of the entry, must be at most one less than the size of the vector returned by enumerationEntryNames().

Returns:

The display name of the enumeration entry if set, or otherwise the name of the entry.

inline std::string enumerationEntryEffectiveDisplayName(std::size_t parameterIndex, std::string const &entryName) const

Get the effective display name of an enumeration entry of an enumeration parameter (parameter by index, entry by name)

For a parameter of type ParameterInfo::Type::Enumeration return the effective display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a version of this method that doesn’t require support for std::optional, ParameterInfo::getEnumerationEntryDisplayName().

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • parameterIndex – The index of the parameter, must be at most one less than the value returned by parameterCount().

  • entryName – The name of the enumeration entry

Returns:

The display name of the enumeration entry if set, or otherwise the name of the entry.

inline std::string enumerationEntryEffectiveDisplayName(std::string const &parameterName, std::size_t entryIndex) const

Get the effective display name of an enumeration entry of an enumeration parameter (parameter by name, entry by index)

For a parameter of type ParameterInfo::Type::Enumeration return the effective display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a version of this method that doesn’t require support for std::optional, ParameterInfo::getEnumerationEntryDisplayName().

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • parameterName – The name of the parameter

  • entryIndex – The index of the entry, must be at most one less than the size of the vector returned by enumerationEntryNames().

Returns:

The display name of the enumeration entry if set, or otherwise the name of the entry.

inline std::string enumerationEntryEffectiveDisplayName(std::string const &parameterName, std::string const &entryName) const

Get the effective display name of an enumeration entry of an enumeration parameter (parameter by name, entry by name)

For a parameter of type ParameterInfo::Type::Enumeration return the effective display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a version of this method that doesn’t require support for std::optional, ParameterInfo::getEnumerationEntryDisplayName().

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

  • parameterName – The name of the parameter

  • entryName – The name of the enumeration entry

Returns:

The display name of the enumeration entry if set, or otherwise the name of the entry.

inline int64_t parameterIntegerIncrement(std::size_t parameterIndex) const

Get the integer increment of a parameter (by index)

For ParameterInfo::Type::Integer type parameters this will return the increment value required to obtain a valid value of this parameter. Specifically, a valid value for the given integer must take the form value = minimum + N * increment, where N is an arbitrary positive integer.

If the parameter is not of integer type, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

parameterIndex – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The increment of the integer parameter

inline int64_t parameterIntegerIncrement(std::string const &parameterName) const

Get the integer increment of a parameter (by name)

For ParameterInfo::Type::Integer type parameters this will return the increment value required to obtain a valid value of this parameter. Specifically, a valid value for the given integer must take the form value = minimum + N * increment, where N is an arbitrary positive integer.

If the parameter is not of integer type, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

parameterName – The name of the parameter

Returns:

The increment of the integer parameter

inline int64_t parameterIntegerMinimum(std::size_t parameterIndex) const

Get the integer minimum value of a parameter (by index)

If the parameter is not of integer type, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

parameterIndex – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The minimum of the integer parameter

inline int64_t parameterIntegerMinimum(std::string const &parameterName) const

Get the integer minimum value of a parameter (by name)

If the parameter is not of integer type, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

parameterName – The name of the parameter

Returns:

The minimum of the integer parameter

inline int64_t parameterIntegerMaximum(std::size_t parameterIndex) const

Get the integer maximum value of a parameter (by index)

If the parameter is not of integer type, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

parameterIndex – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The maximum of the integer parameter

inline int64_t parameterIntegerMaximum(std::string const &parameterName) const

Get the integer maximum value of a parameter (by name)

If the parameter is not of integer type, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

parameterName – The name of the parameter

Returns:

The maximum of the integer parameter

inline double parameterFloatIncrement(std::size_t parameterIndex) const

Get the floating point increment of a parameter (by index)

For ParameterInfo::Type::Float type parameters this will return an indication of the increment to use while the user is editing this parameter. If an increment is actually enforced for floating point values, it means that the supplied value will be rounded to the nearest allowed value upon write.

If the parameter is not of floating point, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

parameterIndex – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The increment of the floating point parameter

inline double parameterFloatIncrement(std::string const &parameterName) const

Get the floating point increment of a parameter (by name)

For ParameterInfo::Type::Float type parameters this will return an indication of the increment to use while the user is editing this parameter. If an increment is actually enforced for floating point values, it means that the supplied value will be rounded to the nearest allowed value upon write.

If the parameter is not of floating point, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

parameterName – The name of the parameter

Returns:

The increment of the floating point parameter

inline double parameterFloatMinimum(std::size_t parameterIndex) const

Get the floating point minimum of a parameter (by index)

If the parameter is not of floating point, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

parameterIndex – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The minimum of the floating point parameter

inline double parameterFloatMinimum(std::string const &parameterName) const

Get the floating point minimum of a parameter (by name)

If the parameter is not of floating point, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

parameterName – The name of the parameter

Returns:

The minimum of the floating point parameter

inline double parameterFloatMaximum(std::size_t parameterIndex) const

Get the floating point maximum of a parameter (by index)

If the parameter is not of floating point, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

parameterIndex – The index of the parameter, must be at most one less than the value returned by parameterCount().

Returns:

The maximum of the floating point parameter

inline double parameterFloatMaximum(std::string const &parameterName) const

Get the floating point maximum of a parameter (by name)

If the parameter is not of floating point, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

parameterName – The name of the parameter

Returns:

The maximum of the floating point parameter

inline explicit ParameterInfo(fluxEngine_C_v1_ParameterInfo *wrapped)

Wrapping constructor.

This constructor wraps the underlying C handle and takes ownership of it. This means that once this object is destroyed the C handle will be freed.

Users will typically not need to call this constructor, as the C++ wrappers for other objects will return this structure directly.

Parameters:

wrapped – The C handle to wrap

struct EnumerationEntry

Enumeration entry.

This structure describes an enumeration entry. It is only available on systems with C++17 support (requiring std::optional). It is part of the ParameterInfo::Parameter structure for ParameterInfo::Type::Enumeration type parameters.

Public Functions

inline std::string effectiveDisplayName() const

Get the effective display name of the enumeration entry.

If the display name is not set, the entry’s name will be returned instead.

Returns:

The effective display name of the enumeration entry

Public Members

std::string name

The name of the enumeration entry.

This will be unique within the enumeration parameter.

int64_t value

The value of the enumeration entry.

This should be unique within the enumeration parameter, but aliases for the same value may exist. (The first entry in the list is the canonical name.)

std::optional<std::string> displayName

The display name of the enumeration entry.

If this is available this contains a more user-friendly string that describes this entry. If this is not available for the given enumeration entry this will be std::nullopt.

struct Parameter

Complete parameter information.

This structure contains all of the information of a given parameter collected into a single structure. It is returned by both ParameterInfo::parameter() and ParameterInfo::parameters().

As std::variant as well as std::optional are present in this structure C++17 support is required for it to be available.

Public Functions

inline std::string effectiveDisplayName() const

Get the effective display name of the parameter.

If the display name is not set, the parameter’s name will be returned instead.

Returns:

The effective display name of the parameter

inline std::optional<int64_t> integerIncrement() const

Get the integer increment of the parameter.

Returns the integer increment of the parameter, or std::nullopt if this is not an integer parameter. This accessor exists for convenience reasons to make accessing this information in case of a known integer parameter easier.

Returns:

The integer increment of the parameter

inline std::optional<int64_t> integerMinimum() const

Get the integer minimum of the parameter.

Returns the integer minimum of the parameter, or std::nullopt if this is not an integer parameter. This accessor exists for convenience reasons to make accessing this information in case of a known integer parameter easier.

Returns:

The integer minimum of the parameter

inline std::optional<int64_t> integerMaximum() const

Get the integer maximum of the parameter.

Returns the integer maximum of the parameter, or std::nullopt if this is not an integer parameter. This accessor exists for convenience reasons to make accessing this information in case of a known integer parameter easier.

Returns:

The integer maximum of the parameter

inline std::optional<double> floatIncrement() const

Get the floating point increment of the parameter.

Returns the floating point increment of the parameter, or std::nullopt if this is not an integer parameter. This accessor exists for convenience reasons to make accessing this information in case of a known integer parameter easier.

Returns:

The floating point increment of the parameter

inline std::optional<double> floatMinimum() const

Get the floating point minimum of the parameter.

Returns the floating point minimum of the parameter, or std::nullopt if this is not an integer parameter. This accessor exists for convenience reasons to make accessing this information in case of a known integer parameter easier.

Returns:

The floating point minimum of the parameter

inline std::optional<double> floatMaximum() const

Get the floating point maximum of the parameter.

Returns the floating point maximum of the parameter, or std::nullopt if this is not an integer parameter. This accessor exists for convenience reasons to make accessing this information in case of a known integer parameter easier.

Returns:

The floating point maximum of the parameter

Public Members

std::string name

The name of the parameter.

This will be unique within the parameter information structure.

Type type = {}

The type of the parameter.

AccessMode accessMode = {}

The access mode of the parameter.

The access mode determines if a parameter can be read from or written to &#8212; or, in case of commands, if it can be executed.

std::optional<std::string> displayName

The display name of the parameter.

If set this is a more human-readable name of the parameter.

std::optional<std::string> shortDescription

A short description of the parameter.

If set this is typically shown in form of a tool-tip when hovering over a parameter.

std::optional<std::string> longDescription

A long description of the parameter.

std::vector<std::string> affectedParameters

A list of affected parameters.

If the value of this parameter is changed by the user, this list of parameter names indicates which parameters may also change due to that write. Affected parameters may have a different value, access mode, minmum, maximum or increment when a parameter changes.

The names in this list denote the unique name of each affected parameter, not the display name.

It is not necessary that a change to this parameter actually changes one of the affected parameters, it only indicates that such a change is possible.

std::variant<std::monostate, std::string, int64_t, double, bool> defaultValue

The default value of a parameter.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that &#8212; though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.)

For parameters describing how to connect to a specific device there may be a default value, and this field will contain that value.

If the field is of std::monostate type there is no default value present.

If the field is of any other type it will contain the default value depending on the type of the parameter. String and file parameters will have default values in the form of a std::string, integer and enumeration parameters will have default values in form of an int64_t, floating point parmaeters will have default values in form of a double, and boolean parameters will have default values in form of a bool.

std::optional<std::string> unit

The unit of the value.

Numeric (integer and floating point) parameters may have a unit associated with them, such as “ms” or “Hz”. If present this will contain that unit.

Note that the unit is encoded as UTF-8, and the unit prefix for “microseconds” is represented with a greek mu, which is not part of the ASCII subset of UTF-8.

This will always be std::nullopt for parameters that do not have a unit (because it is either not set or they are of a type that doesn’t have units).

std::vector<EnumerationEntry> enumerationEntries

The list of available enumeration entries.

For ParameterInfo::Type::Enumeration type parameters this will contain the list of all entries in the given enumeration.

std::variant<std::monostate, int64_t, double> minimum

The minimum value.

For numeric (integer and floating point) parameters this will contain the lowest value that the parameter accepts.

In all other cases this will be a std::monostate.

std::variant<std::monostate, int64_t, double> maximum

The maximum value.

For numeric (integer and floating point) parameters this will contain the largest value that the parameter accepts.

In all other cases this will be a std::monostate.

std::variant<std::monostate, int64_t, double> increment

The increment value.

For ParameterInfo::Type::Integer type parameters this will contain the increment value required to obtain a valid value of this parameter. Specifically, a valid value for the given integer must take the form value = minimum + N * increment, where N is an arbitrary positive integer.

For ParameterInfo::Type::Float type parameters this will give an indication of the increment to use while the user is editing this parameter. If an increment is actually enforced for floating point values, it means that the supplied value will be rounded to the nearest allowed value upon write.

In all other cases this will be a std::monostate.