mv_plugin_control.h File Reference

API function definitions for controlling the plugin instance. More...

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

Functions
MVLibExport void	MV_Log (MVPlugin_t handle, MVSeverityLevel_t severity, const char *message)
	Logs a message of given severity. More...
MVLibExport const char *	MV_GetMVCodeString (MVCode_t code)
	Gets a constant string representation of the MVCode_t return code. More...
MVLibExport const char *	MV_GetMVCodeMessage (MVCode_t code)
	Gets the plain text documentation of the MVCode_t return code. More...
MVLibExport uint32_t	MV_Plugin_GetId (MVPlugin_t handle)
	Gets the ID of the calling plugin. More...
MVLibExport MVCode_t	MV_Plugin_SetUserData (MVPlugin_t handle, void *pUserData)
	Sets the plugin's user data. More...
MVLibExport MVCode_t	MV_Plugin_GetUserData (MVPlugin_t handle, void **pUserData)
	Gets the plugin's user data. More...
MVLibExport MVCode_t	MV_Plugin_GetConfig (MVPlugin_t handle, MVPluginConfig_t *pConfig)
	Gets the plugin's configuration. More...
MVLibExport void	MV_PluginConfig_Clear (MVPluginConfig_t *pConfig)
	Destroys the plugin's configuration. More...

Detailed Description

API function definitions for controlling the plugin instance.

Function Documentation

MV_GetMVCodeMessage()

MVLibExport const char * MV_GetMVCodeMessage

(

MVCode_t

code

)

Gets the plain text documentation of the MVCode_t return code.

Parameters

[in]

code

is the MVCode_t whose documentation string is queried.

Returns

The documentation string of the MVCode_t, e.g. "The application that is specified in the recipe file could not be loaded.".

MV_GetMVCodeString()

MVLibExport const char * MV_GetMVCodeString

(

MVCode_t

code

)

Gets a constant string representation of the MVCode_t return code.

Parameters

[in]

code

is the MVCode_t whose string representation is queried.

Returns

The string representation of the MVCode_t, e.g. "MV_CODE_PREP_RECIPE".

MV_Log()

MVLibExport void MV_Log	(	MVPlugin_t	handle,
		MVSeverityLevel_t	severity,
		const char *	message
	)

Logs a message of given severity.

Parameters

[in]	handle	is the Communicator handle for the plugin instance.
[in]	severity	is the log level; one of eMVSeverity_Debug, eMVSeverity_Info, eMVSeverity_Warning, eMVSeverity_Error, or eMVSeverity_Critical.
[in]	message	is the string that is logged.

MV_Plugin_GetConfig()

MVLibExport MVCode_t MV_Plugin_GetConfig	(	MVPlugin_t	handle,
		MVPluginConfig_t *	pConfig
	)

Gets the plugin's configuration.

Remarks

This function does not create a copy of the plugin configuration but merely references the current one. As such, it is cheap and should be called in every function requiring access to the current plugin config anew instead of storing it long-term; in particular, it loses validity between consecutive runs of the same plugin instance.

Parameters

[in]	handle	is the Communicator handle for the plugin instance.
[out]	pConfig	points to the MVPluginConfig_t variable in which the configuration is stored.

Returns

• MV_CODE_OK The plugin configuration has been successfully stored into the variable pointed to by pConfig.
• MV_CODE_INV_HANDLE Either the provided plugin handle or the pointer pConfig are not valid.

MV_Plugin_GetId()

MVLibExport uint32_t MV_Plugin_GetId

(

MVPlugin_t

handle

)

Gets the ID of the calling plugin.

Upon registration with the Communicator, plugins are assigned a unique identifier.

Parameters

[in]

handle

is the Communicator handle for the plugin instance.

Returns

The plugin's ID.

MV_Plugin_GetUserData()

MVLibExport MVCode_t MV_Plugin_GetUserData	(	MVPlugin_t	handle,
		void **	pUserData
	)

Gets the plugin's user data.

Recalls the void pointer to the user data previously associated with the plugin handle. The pointer must be cast to the appropriate type for the implementation-defined user data structure.

Usage:

MyUserData *ptr;
if (MV_IsCodeOk(MV_Plugin_GetUserData(handle, (void**)&ptr)) {
  // Do something with the user data struct `*ptr`.
} else {
  // Could not retrieve user data.
}

Parameters

[in]	handle	is the Communicator handle for the plugin instance.
[out]	pUserData	points to the pointer which is set to the plugin's user data structure.

Returns

• MV_CODE_OK The pointer to the user data has been successfully retrieved from the plugin instance handle.
• MV_CODE_INV_HANDLE The provided plugin handle is not valid.
• MV_CODE_INV_VALUE The provided pointer pUserData is NULL.
• MV_CODE_INV_USER_DATA No user data has previously been stored in the plugin instance handle, or it has since been cleared.

MV_Plugin_SetUserData()

MVLibExport MVCode_t MV_Plugin_SetUserData	(	MVPlugin_t	handle,
		void *	pUserData
	)

Sets the plugin's user data.

Plugins may store their internal state in an implementation-defined struct which is typically allocated in MVOpen or MVStart. This function is then used to associate an opaque pointer to this user data with the plugin handle. Plugins are responsible for freeing that allocation again, typically in MVStop or MVClose.

Parameters

[in]	handle	is the Communicator handle for the plugin instance.
[in]	pUserData	points to the user data memory that is associated with the handle.

Returns

• MV_CODE_OK The provided pointer to the user data has been successfully stored in the plugin instance handle.
• MV_CODE_INV_HANDLE The provided plugin handle is not valid.

MV_PluginConfig_Clear()

MVLibExport void MV_PluginConfig_Clear

(

MVPluginConfig_t *

pConfig

)

Destroys the plugin's configuration.

Remarks

This function is deprecated and does nothing other than resetting the value pointed to by pConfig to NULL. In particular, it does not free any memory since MV_Plugin_GetConfig() does not allocate a copy but merely provides a view into the original and calling this function is no longer required.

Parameters

[in,out]

pConfig

points to the plugin's configuration that is no longer needed.