mv_plugin_config.h File Reference

API functions for plugin configuration. More...

#include <mvtec/plugin/mv_decl.h>
#include <mvtec/plugin/mv_types.h>

Functions
MVLibExport MVCode_t	MV_PluginUserParameterDescription_AddUserParameter (MVPluginUserParameterDescription_t description, const char *parameter, MVValue_t value)
	Adds a user parameter with the unique identifier param to description. More...
MVLibExport MVCode_t	MV_PluginUserParameterDescription_SetPresentationProperty (MVPluginUserParameterDescription_t description, const char *parameter, MVPluginParameterPresentationProperty_t property, MVValue_t value)
	Specifies how the user parameter is presented to the user in the configuration interface. More...
MVLibExport MVCode_t	MV_PluginUserParameterDescription_ImposeConstraint (MVPluginUserParameterDescription_t description, const char *parameter, MVPluginParameterConstraint_t constraint, MVValue_t value)
	Enforces the user parameter values to meet certain requirements. More...
MVLibExport MVCode_t	MV_PluginConfig_GetParameter (MVPluginConfig_t config, uint32_t parameter, MVValue_t *pValue)
	Gets a parameter value from a plug-in configuration. More...
MVLibExport MVCode_t	MV_PluginConfig_GetUserParameter (MVPluginConfig_t config, const char *parameter, MVValue_t *pValue)
	Retrieves the currently set value of a user parameter stored in the given configuration. More...
MVLibExport MVCode_t	MV_PluginConfigValidation_SetMessage (MVPluginConfigValidation_t validation, MVPluginConfigValidationErrorState_t level, const char *message)
	Sets a message for the configuration. More...
MVLibExport MVCode_t	MV_PluginConfigValidation_DisableUserParameter (MVPluginConfigValidation_t validation, const char *parameter)
	Marks a user parameter as disabled. More...
MVLibExport MVCode_t	MV_PluginConfigValidation_SetUserParameterErrorState (MVPluginConfigValidation_t validation, const char *parameter, MVPluginConfigValidationErrorState_t level)
	Sets the error state of a user parameter. More...

Detailed Description

API functions for plugin configuration.

Function Documentation

MV_PluginConfig_GetParameter()

MVLibExport MVCode_t MV_PluginConfig_GetParameter	(	MVPluginConfig_t	config,
		uint32_t	parameter,
		MVValue_t *	pValue
	)

Gets a parameter value from a plug-in configuration.

Parameters

[in]	config	is the MVPluginConfig_t that is queried.
[in]	parameter	identifies the parameter which is retrieved from the plug-in's configuration. Currently, only the plug-in access level can be retrieved through MV_PARAM_CONFIG_ACCESS_LEVEL.
[out]	pValue	points to a MVValue_t which is then initialized to a copy of the desired plug-in configuration parameter.

Returns

• MV_CODE_OK pValue was successfully initialized to a copy of the specified parameter. It is the caller's obligation to destroy the value by MV_Value_Clear().
• MV_CODE_INV_HANDLE One of the following:
  • The config is NULL. Make sure to pass the handle which has been retrieved from MV_Plugin_GetConfig().
  • The pointer pValue is NULL. Make sure it points to an uninitialized variable of type MVValue_t.
• MV_CODE_INV_PARAM The queried parameter key does not apply to plug-in configurations.

MV_PluginConfig_GetUserParameter()

MVLibExport MVCode_t MV_PluginConfig_GetUserParameter	(	MVPluginConfig_t	config,
		const char *	parameter,
		MVValue_t *	pValue
	)

Retrieves the currently set value of a user parameter stored in the given configuration.

Parameters

[in]	config	is the MVPluginConfig_t that is queried.
[in]	parameter	identifies the user parameter whose value is retrieved.
[out]	pValue	points to the MVValue_t in which the parameter value is stored.

Returns

• MV_CODE_OK pValue was successfully initialized to a copy of the specified user parameter. It is the caller's obligation to destroy the value by MV_Value_Clear().
• MV_CODE_INV_HANDLE The config is NULL. Make sure to pass the handle which has been retrieved from MV_Plugin_GetConfig().
• MV_CODE_INV_VALUE The pointer pValue is NULL. Make sure it points to an uninitialized variable of type MVValue_t.
• MV_CODE_UNK_USERPARAM The queried user parameter has not been exposed to the user parameter description.

MV_PluginConfigValidation_DisableUserParameter()

MVLibExport MVCode_t MV_PluginConfigValidation_DisableUserParameter	(	MVPluginConfigValidation_t	validation,
		const char *	parameter
	)

Marks a user parameter as disabled.

Disabled parameters cannot be interacted with. They are commonly displayed grayed out. This could be used, for example, when the value of a different parameter invalidates this parameter or when the parameter in question only applies to certain models of a hardware device and does not apply to the connected device.

Parameters

[in]	validation	is the validation structure accumulating the validation results.
[in]	parameter	is the identifier of the parameter that is marked as disabled.

Returns

• MV_CODE_OK The specified user parameter is now marked as disabled.
• MV_CODE_INV_HANDLE The validation is NULL. Make sure to pass the handle which MVValidate has been called with.
• MV_CODE_UNK_USERPARAM The queried user parameter has not been exposed to the user parameter description.

MV_PluginConfigValidation_SetMessage()

MVLibExport MVCode_t MV_PluginConfigValidation_SetMessage	(	MVPluginConfigValidation_t	validation,
		MVPluginConfigValidationErrorState_t	level,
		const char *	message
	)

Sets a message for the configuration.

The message refers to the plug-in configuration in its entirety. A faulty plug-in configuration, involving one or multiple parameter values, is marked with with a warning or error symbol in the configuration interface.

Parameters

[in]	validation	is the validation structure accumulating the validation results.
[in]	level	is the error level.
[in]	message	is the UTF-8 encoded string representing the message.

Returns

• MV_CODE_OK The message was successfully stored in the validation object.
• MV_CODE_INV_HANDLE The validation is NULL. Make sure to pass the handle which MVValidate has been called with.
• MV_CODE_FAILED The error level is not valid.

MV_PluginConfigValidation_SetUserParameterErrorState()

MVLibExport MVCode_t MV_PluginConfigValidation_SetUserParameterErrorState	(	MVPluginConfigValidation_t	validation,
		const char *	parameter,
		MVPluginConfigValidationErrorState_t	level
	)

Sets the error state of a user parameter.

Erroneous parameters are marked with a warning or error symbol in the configuration interface.

It is recommended to subsequently call MV_PluginConfigValidation_SetMessage() with the same error level to give a detailed explanation about the issue.

Parameters

[in]	validation	is the validation structure accumulating the validation results.
[in]	parameter	is the identifier of the user parameter that is marked as erroneous.
[in]	level	is the error level.

Returns

• MV_CODE_OK The specified user parameter's error state was successfully set.
• MV_CODE_INV_HANDLE The validation is NULL. Make sure to pass the handle which MVValidate has been called with.
• MV_CODE_FAILED The error level is not valid.
• MV_CODE_UNK_USERPARAM The queried user parameter has not been exposed to the user parameter description.

MV_PluginUserParameterDescription_AddUserParameter()

MVLibExport MVCode_t MV_PluginUserParameterDescription_AddUserParameter	(	MVPluginUserParameterDescription_t	description,
		const char *	parameter,
		MVValue_t	value
	)

Adds a user parameter with the unique identifier param to description.

The operation is performed instantly and the parameter description is changed accordingly.

Parameters

[in]	description	is the MVPluginUserParameterDescription_t to which the parameter is added.
[in]	parameter	is the unique identifier for the parameter.
[in]	value	is the default value for the parameter. Only scalar values of numeric types, boolean, or string are supported.

Returns

• MV_CODE_OK The user parameter was successfully added to the description.
• MV_CODE_INV_HANDLE The description is NULL. Make sure to pass the handle which MVExpose has been called with.
• MV_CODE_INV_VALUE One of the following:
  • The value is NULL. Make sure to properly initialize it using MV_Value_Scalar_Init() or MV_Value_Array_Init().
  • The string provided as parameter contains characters which are not allowed. Only alphanumeric characters, dashes (-) and underscores (_) are permissible.
• MV_CODE_USERPARAM_REDECL A user parameter with the name parameter has already been added to the description.
• MV_CODE_INV_VALUE_TYPE value is not a scalar. Currently, only scalar user parameters are supported.
• MV_CODE_INV_DATA_TYPE value is not of a data type which is supported. In particular, user parameter must be of fixed data type; e.g. eMVDataType_Variant is not eligible.

MV_PluginUserParameterDescription_ImposeConstraint()

MVLibExport MVCode_t MV_PluginUserParameterDescription_ImposeConstraint	(	MVPluginUserParameterDescription_t	description,
		const char *	parameter,
		MVPluginParameterConstraint_t	constraint,
		MVValue_t	value
	)

Enforces the user parameter values to meet certain requirements.

Remarks

Note that imposing a constraint replaces any existing constraint.

Parameters

[in]	description	is the MVPluginUserParameterDescription_t containing the parameter
[in]	parameter	is the unique identifier for the parameter.
[in]	constraint	is the type of constraint that is enforced.
[in]	value	contains the value(s) for the constraint. The exact format depends on the constraint. See the documentation of MVPluginParameterConstraint_t for the required format.

Returns

• MV_CODE_OK The constraint was successfully imposed.
• MV_CODE_INV_HANDLE The description is NULL. Make sure to pass the handle which MVExpose has been called with.
• MV_CODE_INV_VALUE The value is NULL. Make sure to properly initialize it using MV_Value_Scalar_Init() or MV_Value_Array_Init().
• MV_CODE_FAILED The provided constraint type is unknown.
• MV_CODE_UNK_USERPARAM A user parameter with the name parameter has not yet been added to the description.
• MV_CODE_INV_VALUE_TYPE The value type of value does not match the requirement for the selected type of constraint.
• MV_CODE_INV_DATA_TYPE The data type of value does not match the requirement for the selected type of constraint.
• MV_CODE_INV_CONSTRAINT The provided value does not define a reasonable constraint. This may indicate that the constraint does not permit any valid values or that the initial default value of the parameter does not obey the constraint.

MV_PluginUserParameterDescription_SetPresentationProperty()

MVLibExport MVCode_t MV_PluginUserParameterDescription_SetPresentationProperty	(	MVPluginUserParameterDescription_t	description,
		const char *	parameter,
		MVPluginParameterPresentationProperty_t	property,
		MVValue_t	value
	)

Specifies how the user parameter is presented to the user in the configuration interface.

Depending on the enum value of the property parameter, one of the following presentation properties can be manipulated:

• eMVPluginParameterPresentationProperty_DisplayName: The user-facing name of the parameter which is displayed in a graphical configuration window. value is a scalar String value.
• eMVPluginParameterPresentationProperty_Prefix: The text of a label which is supposed to be displayed in front of the actual parameter value. Can be used for currency symbols. value is a scalar String value.
• eMVPluginParameterPresentationProperty_Suffix: The text of a label which is supposed to be displayed after the actual parameter value. Can be used for units. value is a scalar String value.
• eMVPluginParameterPresentationProperty_Category: The category under which the parameter should be grouped. value is a scalar String value.
• eMVPluginParameterPresentationProperty_PreferredWidget: The widget which should be used in the configuration UI to represent the parameter. value is a scalar UInt32 value corresponding to an enumerator in MVPluginParameterWidget_t.

Remarks

Repeatedly setting the same presentation property within the same call to MVExpose will replace its previous value.

Parameters

[in]	description	is the MVPluginUserParameterDescription_t containing the parameter.
[in]	parameter	is the unique identifier for the parameter.
[in]	property	is the presentation property that is changed
[in]	value	contains the value for the presentation property. The exact format depends on the property. See documentation of MVPluginParameterPresentationProperty_t for the required format.

Returns

• MV_CODE_OK The user parameter's presentation property was successfully set.
• MV_CODE_INV_HANDLE The description is NULL. Make sure to pass the handle which MVExpose has been called with.
• MV_CODE_INV_VALUE The value is NULL. Make sure to properly initialize it using MV_Value_Scalar_Init() or MV_Value_Array_Init().
• MV_CODE_FAILED The provided property is unknown.
• MV_CODE_UNK_USERPARAM A user parameter with the name parameter has not yet been added to the description.
• MV_CODE_INV_VALUE_TYPE value is not a scalar. For now, only scalar values are allowed for presentation properties.
• MV_CODE_INV_DATA_TYPE The data type of value does not match the requirement for the selected presentation property.