API function definitions for actions. More...

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

Functions
MVLibExport MVCode_t	MV_QueueAction (MVPlugin_t handle, MVAction_t pAction, uint32_t pActionId)
	Enqueues a new action that is to be processed by the vision system. More...

MVLibExport MVCode_t	MV_QueueAction_WithInfo (MVPlugin_t handle, MVAction_t pAction, MVActionInfo_t pActionInfo)
	Enqueues a new action and provides additional information about it. More...

MVLibExport MVCode_t	MV_Action_Init (MVActionType_t type, MVAction_t *pAction)
	Initializes a new action of type MVAction_t. More...

MVLibExport void	MV_Action_Clear (MVAction_t *pAction)
	Destroys the action. More...

MVLibExport MVCode_t	MV_Action_SetParameter (MVAction_t action, uint32_t parameter, MVValue_t value)
	Sets a parameter of an action to a given value. More...

MVLibExport MVCode_t	MV_Action_Tuple_SetParameter (MVAction_t action, uint32_t parameter, MVTuple_t tuple)
	Sets a parameter of an action to a given tuple. More...

MVLibExport MVActionType_t	MV_Action_GetType (MVAction_t action)
	Returns the type of a given action. More...

MVLibExport MVCode_t	MV_ActionInfo_GetParameter (MVActionInfo_t info, uint32_t parameter, MVValue_t *pValue)
	Gets a parameter value from the action info. More...

MVLibExport void	MV_ActionInfo_Clear (MVActionInfo_t *pActionInfo)
	Destroys the action info. More...

Detailed Description

API function definitions for actions.

Actions

The communication between plug-ins inside the Communicator and the vision system (i.e. MERLIC) mainly utilizes two FIFO queues, one for either direction:

Actions are commands from a plug-in to MERLIC which affect the state of the vision system. Examples are the triggering of executions, the loading of recipes, etc. These actions are queued by the various plug-ins and dealt with in order by the vision system. No immediate feedback is provided other than that an action was enqueued correctly; however, each action is assigned an ActionId upon being queued which may be used to keep track of the events that result from the action as it is processed.
Events (-> mv_event.h)

     _____________________________________________
    |          Actions              |             |
    V                               |             |
 ________                      ___________    ___________
/        \                    /           \  /           \
| MERLIC |                    | Plug-in 2 |  | Plug-in 1 |
\________/                    \___________/  \___________/
    |                               ^             ^
    |_______________________________|_____________|
                Events

The API functions to manipulate actions are listed below.

Actions can hold parameters. For example, these are used to specify the ID of the desired recipe in the PrepareRecipe action. Parameters are of type MVValue_t. The basic concepts and API functions for accessing the contained data are outlined below.

Refer to mv_action_def.h for a listing of available actions and their respective parameters.

Function Documentation

◆ MV_Action_Clear()

MVLibExport void MV_Action_Clear ( MVAction_t * pAction )

Destroys the action.

Every initialization of an action by MV_Action_Init() must be balanced by either a call to MV_Action_Clear(), MV_QueueAction(), or MV_QueueAction_WithInfo(). It is not necessary to clear an action which has been queued.

Parameters

[in,out] pAction points to the action that is destroyed.

◆ MV_Action_GetType()

MVLibExport MVActionType_t MV_Action_GetType ( MVAction_t action )

Returns the type of a given action.

Parameters

[in] action is the action whose type is to be determined.

Returns: The MVActionType_t enum value corresponding to the type of action.

◆ MV_Action_Init()

MVLibExport MVCode_t MV_Action_Init	(	MVActionType_t	type,
		MVAction_t *	pAction
	)

Initializes a new action of type MVAction_t.

Parameters

[in]	type	is an enum value indicating the action type, e.g., eMVAction_StartSingleJob.
[out]	pAction	points to the action variable that is initialized.

Returns

MV_CODE_OK The action data structure was successfully initialized.
MV_CODE_INV_HANDLE The pointer pAction is NULL. Provide a pointer to a valid variable of type MVAction_t which is to be initialized.
MV_CODE_UNK_ACTION The value of type is not a valid member of the enumeration MVActionType_t.

◆ MV_Action_SetParameter()

MVLibExport MVCode_t MV_Action_SetParameter	(	MVAction_t	action,
		uint32_t	parameter,
		MVValue_t	value
	)

Sets a parameter of an action to a given value.

Depending on the type of the action, it is parametrized in different ways. The parameter is identified by numeric constants which are defined in mv_parameters.h. Refer to mv_action_def.h for a list of all available actions and their respective valid identifiers.

Depending upon the parameter, it is either of type MVValue_t or MVTuple_t. This function is for storing value parameters; see MV_Action_Tuple_SetParameter() for the analogous function for tuples.

Refer to mv_value.h for the API functions for manipulating values. The value type that is realized, as well as its dimensionality (scalar vs array), must match the expectation for the given parameter. Refer to mv_action_def.h for a list of parameters and their expected value type.

Remarks: Calling this function will copy the value of the parameter, such that the caller may destroy the value passed as an argument immediately after calling by way of MV_Value_Clear(). Likewise, when an action is destroyed through MV_Action_Clear(), its parameter values are automatically destroyed as well.

Parameters

[in]	action	is the action whose parameter is set.
[in]	parameter	identifies the parameter that is set; must match one of the parameters supported by actions of the given type.
[in]	value	is the MVValue_t that is copied into the action.

Returns

MV_CODE_OK The provided value was successfully stored in the action for the given parameter. value may now be cleared.
MV_CODE_INV_HANDLE One or both of action or value are NULL. Make sure the arguments are properly initialized through their respective initialization routines, MV_Action_Init() and MV_Value_Scalar_Init() or MV_Value_Array_Init().
MV_CODE_INV_OBJECT The opaque data structure referenced by action is not properly initialized.
MV_CODE_INV_PARAM The provided parameter does not apply to the action's type. See mv_action_def.h for a table of supported parameters.
MV_CODE_VALUE_TYPE_MISMATCH The provided value's type does not match the expectation for the specified parameter.
MV_CODE_DATA_TYPE_MISMATCH The provided value's data type does not match the expectation for the specified parameter.
MV_CODE_UNK_ACTION The MVActionType_t of the provided action is unknown. Make sure action is initialized with a valid type.

◆ MV_Action_Tuple_SetParameter()

MVLibExport MVCode_t MV_Action_Tuple_SetParameter	(	MVAction_t	action,
		uint32_t	parameter,
		MVTuple_t	tuple
	)

Sets a parameter of an action to a given tuple.

This function works analogous to MV_Action_SetParameter() but is used to set parameter tuples rather than individual values.

Refer to mv_tuple.h for the API functions for manipulating tuples.

Parameters

[in]	action	is the action whose parameter is set.
[in]	parameter	identifies the parameter that is set; must match one of the parameters supported by actions of the given type.
[in]	tuple	is the MVTuple_t that is copied into the action.

Returns

MV_CODE_OK upon successful completion; an error code otherwise.

MV_CODE_OK The provided tuple was successfully stored in the action for the given parameter. value may now be cleared.
MV_CODE_INV_HANDLE One or both of action or tuple are NULL. Make sure the arguments are properly initialized through their respective initialization routines, MV_Action_Init() and MV_Tuple_Init().
MV_CODE_INV_OBJECT The opaque data structure referenced by action is not properly initialized.
MV_CODE_INV_PARAM The provided parameter does not apply to the action's type. See mv_action_def.h for a table of supported parameters.

◆ MV_ActionInfo_Clear()

MVLibExport void MV_ActionInfo_Clear ( MVActionInfo_t * pActionInfo )

Destroys the action info.

Every initialization of action info by a call to MV_QueueAction_WithInfo() must be balanced by a call to this function to free the resources occupied by the action info data.

Parameters

[in,out] pActionInfo points to the action info that is to be destroyed.

◆ MV_ActionInfo_GetParameter()

MVLibExport MVCode_t MV_ActionInfo_GetParameter	(	MVActionInfo_t	info,
		uint32_t	parameter,
		MVValue_t *	pValue
	)

Gets a parameter value from the action info.

Action info can be obtained by enqueuing an action using the MV_QueueAction_WithInfo() function and allows the plug-in to query miscellaneous information that may be provided by the vision system at the time an action is enqueued, but before it is actually processed. This function provides the means to extract that information from the action info.

Remarks

Currently, the action info provides access to two unique identifiers which are selected through one of the following parameter constants:

MV_PARAM_ACTION_ID stores the action ID in the value as an UInt32.
MV_PARAM_JOB_ID stores the job ID in the value as an UInt32; job IDs are only associated with actions of either type eMVAction_StartSingleJob or eMVAction_StartContinuous.

Parameters

[in]	info	is the action info whose parameter is to be retrieved.
[in]	parameter	identifies the parameter which is to be retrieved; must be either MV_PARAM_ACTION_ID or MV_PARAM_JOB_ID.
[in,out]	pValue	points to a value handle that is initialized with a copy of the value of the queried parameter.

Returns

MV_CODE_OK The value of the desired parameter was successfully copied into the MVValue_t pointed to by pValue.
MV_CODE_INV_HANDLE One or both of info or *pValue are NULL. Make sure info has been successfully obtained through MV_QueueAction_WithInfo() and that *pValue has been properly initialized through either MV_Value_Scalar_Init() or MV_Value_Array_Init().
MV_CODE_UNK_PARAM The provided parameter key does not match one of the applicable options listed above.
MV_CODE_UNSET_PARAM The action from which info has been derived was neither of type StartSingleJob, nor StartContinuous and, thus, no job ID has been assigned when it was enqueued.

◆ MV_QueueAction()

MVLibExport MVCode_t MV_QueueAction	(	MVPlugin_t	handle,
		MVAction_t *	pAction,
		uint32_t *	pActionId
	)

Enqueues a new action that is to be processed by the vision system.

An action of type MVAction_t (which was previously initialized and whose parameters have been set) is enqueued in the vision system's action queue.

From there, it will be processed by the vision system as soon as it finished processing all previously enqueued pending actions. This function does not wait for this to happen, nor does a return code of MV_CODE_OK indicate that the action could be processed; merely that it is well-formed and could be enqueued successfully.

When an action is enqueued, it is assigned a unique action ID which can be used by the plug-in to keep track of the events caused by the action. This integer action ID is assigned to the memory pointed to by the function's third parameter.

Remarks: When calling this function, the pointed-to action is consumed as if MV_Action_Clear() was invoked. Hence, the same action cannot be enqueued multiple times, but has to be initialized and constructed anew each time.

Parameters

[in]	handle	is the Communicator handle for the plug-in instance.
[in]	pAction	points to the action that is to be enqueued.
[out]	pActionId	points to the integer that is assigned to the unique ID of the action when it is enqueued; alternatively `NULL` can be provided if the action ID is not of interest.

Returns

MV_CODE_OK The action was enqueued successfully.
MV_CODE_INV_HANDLE The provided plug-in handle is not valid.
MV_CODE_INV_OBJECT The provided action (pointed to by pAction) is not valid.
MV_CODE_ACCESS_DENIED The plug-in does not have the "control" access level needed to queue actions. Ensure that the plug-in declares the "control" capability in MVInfo and is granted access to it when adding the plug-in instance.
MV_CODE_TIMEOUT The attempt to enqueue the action at the vision system timed out. The vision system may not be running at all.
MV_CODE_PLUGIN_NOT_REGISTERED The plug-in is not currently registered. This indicates that MV_QueueAction has been called from a self-spawned thread and outside of its allowed plug-in lifetime.
MV_CODE_FAILED An unknown problem has occurred.

◆ MV_QueueAction_WithInfo()

MVLibExport MVCode_t MV_QueueAction_WithInfo	(	MVPlugin_t	handle,
		MVAction_t *	pAction,
		MVActionInfo_t *	pActionInfo
	)

Enqueues a new action and provides additional information about it.

An action of type MVAction_t (which was previously initialized and whose parameters have been set) is enqueued in the vision system's action queue.

From there, it will be processed by the vision system as soon as it finished processing all previously enqueued pending actions. This function does not wait for this to happen, nor does a return code of MV_CODE_OK indicate that the action could be processed; merely that it is well-formed and could be enqueued successfully.

When an action is enqueued, it is assigned a unique action ID which can be used by the plug-in to keep track of the events caused by the action. If it is the action's intention to start a new job on the vision system, i.e. if the action is either of type eMVAction_StartSingleJob or eMVAction_StartContinuous, then it will additionally be assigned a unique job ID at that time. The output parameter of type MVActionInfo_t holds the information on both the action ID and the job ID and may be queried using the MV_ActionInfo_GetParameter() function. Note that job IDs are assigned regardless of whether or not a job can be started at the time the action is processed by the vision system; if so, a JobStarted event will be emitted which references the job ID.

Remarks: When calling this function, the pointed-to action is consumed as if MV_Action_Clear() was invoked. Hence, the same action cannot be enqueued multiple times, but has to be initialized and constructed anew each time. Also note that if this function is used over MV_QueueAction(), the MVActionInfo_t variable must be destroyed by the caller by way of calling MV_ActionInfo_Clear().

Parameters

[in]	handle	is the Communicator handle for the plug-in instance.
[in]	pAction	points to the action that is to be enqueued.
[out]	pActionInfo	points to an uninitialized action info variable which will be initialized with additional information about the action that has just been enqueued; alternatively `NULL` can be provided if the action info is not of interest, though one may want to consider using MV_QueueAction() in that case instead.

Returns

MV_CODE_OK The action was enqueued successfully.
MV_CODE_INV_HANDLE The provided plug-in handle is not valid.
MV_CODE_INV_OBJECT The provided action (pointed to by pAction) is not valid.
MV_CODE_ACCESS_DENIED The plug-in does not have the "control" access level needed to queue actions. Ensure that the plug-in declares the "control" capability in MVInfo and is granted access to it when adding the plug-in instance.
MV_CODE_PLUGIN_NOT_REGISTERED The plug-in is not currently registered. This indicates that MV_QueueAction has been called from a self-spawned thread and outside of its allowed plug-in lifetime.
MV_CODE_FAILED An unknown problem has occurred.

Functions

Detailed Description

Actions

Function Documentation

◆ MV_Action_Clear()

◆ MV_Action_GetType()

◆ MV_Action_Init()

◆ MV_Action_SetParameter()

◆ MV_Action_Tuple_SetParameter()

◆ MV_ActionInfo_Clear()

◆ MV_ActionInfo_GetParameter()

◆ MV_QueueAction()

◆ MV_QueueAction_WithInfo()