mv_plugin_control.h File Reference

API function definitions for controlling the plug-in 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 plug-in. More...
MVLibExport MVCode_t	MV_Plugin_SetUserData (MVPlugin_t handle, void *pUserData)
	Sets the plug-in's user data. More...
MVLibExport MVCode_t	MV_Plugin_GetUserData (MVPlugin_t handle, void **pUserData)
	Gets the plug-in's user data. More...
MVLibExport MVCode_t	MV_Plugin_GetConfig (MVPlugin_t handle, MVPluginConfig_t *pConfig)
	Gets the plug-in's configuration. More...
MVLibExport void	MV_PluginConfig_Clear (MVPluginConfig_t *pConfig)
	Destroys the plug-in's configuration. More...

Detailed Description

API function definitions for controlling the plug-in 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 plug-in 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 plug-in's configuration.

Remarks

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

Parameters

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

Returns

• MV_CODE_OK The plug-in configuration has been successfully stored into the variable pointed to by pConfig.
• MV_CODE_INV_HANDLE Either the provided plug-in 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 plug-in.

Upon registration with the Communicator, plug-ins are assigned a unique identifier.

Parameters

[in]

handle

is the Communicator handle for the plug-in instance.

Returns

The plug-in's ID.

MV_Plugin_GetUserData()

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

Gets the plug-in's user data.

Recalls the void pointer to the user data previously associated with the plug-in 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 plug-in instance.
[out]	pUserData	points to the pointer which is set to the plug-in's user data structure.

Returns

• MV_CODE_OK The pointer to the user data has been successfully retrieved from the plug-in instance handle.
• MV_CODE_INV_HANDLE The provided plug-in 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 plug-in instance handle, or it has since been cleared.

MV_Plugin_SetUserData()

MVLibExport MVCode_t MV_Plugin_SetUserData	(	MVPlugin_t	handle,
		void *	pUserData
	)

Sets the plug-in's user data.

Plug-ins 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 plug-in handle. Plug-ins are responsible for freeing that allocation again, typically in MVStop or MVClose.

Parameters

[in]	handle	is the Communicator handle for the plug-in 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 plug-in instance handle.
• MV_CODE_INV_HANDLE The provided plug-in handle is not valid.

MV_PluginConfig_Clear()

MVLibExport void MV_PluginConfig_Clear

(

MVPluginConfig_t *

pConfig

)

Destroys the plug-in'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 plug-in's configuration that is no longer needed.