API function definitions for events. More...

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

Functions
MVLibExport MVCode_t	MV_TryGetEvent (MVPlugin_t handle, int32_t timeout, MVEvent_t *pEvent)
	Attempts to retrieve a new event from this plug-in's event queue. More...

MVLibExport MVEventType_t	MV_Event_GetType (MVEvent_t event)
	Returns the type of a given event. More...

MVLibExport void	MV_Event_Clear (MVEvent_t *pEvent)
	Destroys the event. More...

MVLibExport MVCode_t	MV_Event_GetParameter (MVEvent_t event, uint32_t parameter, MVValue_t *pValue)
	Gets a parameter value of an event. More...

MVLibExport MVCode_t	MV_Event_Tuple_GetParameter (MVEvent_t event, uint32_t parameter, MVTuple_t *pTuple)
	Gets a parameter tuple of an event. More...

MVLibExport MVCode_t	MV_Event_GetDataContainerDescriptor (MVEvent_t event, MVDataContainerDescriptor_t *pDescriptor)
	Gets a data container descriptor for the data components of a ResultReady event. More...

Detailed Description

API function definitions for events.

Events

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 (-> mv_action.h)
Events notify the plug-ins of any changes of the active state of the vision state machine, available results, or alert the plug-in that an action could not be processed because it was invalid or is not applicable to the current state of MERLIC. Most events are caused by an action, in which case they carry its actionId. The communicator holds a separate event queue for each plug-in. Every event is put into each plug-in's event queue, regardless of which plug-in issued the associated action. Plug-ins can then get events from their respective queues.

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

The API functions to manipulate events are listed below.

Events can hold parameters. These are used, e.g., to transport the result data as part of the ResultReady event. Parameters are of type MVValue_t. The basic concepts and API functions for accessing the contained data are described below.

Refer to mv_event_def.h for an overview of available events and their respective parameters.

Function Documentation

◆ MV_Event_Clear()

MVLibExport void MV_Event_Clear ( MVEvent_t * pEvent )

Destroys the event.

Every successful retrieval of an event by MV_TryGetEvent() must be balanced by a call to MV_Event_Clear().

Parameters

[in,out] pEvent points to the event that is destroyed.

◆ MV_Event_GetDataContainerDescriptor()

MVLibExport MVCode_t MV_Event_GetDataContainerDescriptor	(	MVEvent_t	event,
		MVDataContainerDescriptor_t *	pDescriptor
	)

Gets a data container descriptor for the data components of a ResultReady event.

This function provides a data container descriptor which contains data component descriptors for each of the transferable data components (e.g. images) which are available as part of the ResultReady event. The data container descriptor does not hold any image data but simply references and describes the available data. The actual data can be fetched from the vision system by providing the descriptor to MV_FetchDataContainer() to obtain a data container.

The type and parameters of the contained data component descriptors reflect the "native" format, image size, etc., in which the data are present in the vision system. They can be overwritten using the functions provided in mv_data_component.h to request the data suitably to the plug-in.

Remarks: Each call to MV_Result_GetDataContainerDescriptor() has to be balanced by a call to MV_DataContainerDescriptor_Clear().

Parameters

[in]	event	is the handle to the ResultReady event that is queried.
[out]	pDescriptor	points to the uninitialized data container descriptor that is initialized.

Returns

MV_CODE_OK pDescriptor has successfully initialized with the data container descriptor.
MV_CODE_INV_HANDLE Either the provided result is not valid or the pointer pDescriptor is NULL.
MV_CODE_INV_OBJECT The opaque data structure referenced by event is not properly initialized.
MV_CODE_UNK_EVENT The event is not a ResultReady event.

◆ MV_Event_GetParameter()

MVLibExport MVCode_t MV_Event_GetParameter	(	MVEvent_t	event,
		uint32_t	parameter,
		MVValue_t *	pValue
	)

Gets a parameter value of an event.

Depending on the type of the event, it is parametrized in different ways. The parameter is identified by a numeric constant which is defined in mv_parameters.h. Refer to mv_event_def.h for a list of all available events and their respective valid identifiers.

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

Refer to mv_value.h for the API functions for accessing values. The value type that is realized, as well as its dimensionality (scalar vs array), is dependent upon the given parameter. Refer to mv_event_def.h for a list of parameters and their value type.

Remarks: Calling this function will copy the value of the parameter contained inside of the event into the value pointed to by the third argument. As such, it becomes the caller's responsibility to destroy said copy by way of MV_Value_Clear() once it is done using it. Likewise, when an event is destroyed through MV_Event_Clear(), its contained parameter values are automatically destroyed as well.

Parameters

[in]	event	is the event whose parameter is retrieved.
[in]	parameter	identifies the parameter that is retrieved; must match one of the parameters supported by events of the given type.
[out]	pValue	points to a MVValue_t which is then initialized to a copy of the desired parameter contained in the event.

Returns

MV_CODE_OK The parameter key applies to the provided event and the variable pointed to by pValue has been initialized with its corresponding value.
MV_CODE_INV_HANDLE One or both of event or pValue are NULL. Make sure event is properly initialized through a successful invocation of MV_TryGetEvent() and that pValue points to an uninitialized writable variable.
MV_CODE_INV_OBJECT The opaque data structure referenced by event is not properly initialized.
MV_CODE_UNK_PARAM The requested parameter key does not apply to the type of the provided event.
MV_CODE_UNSET_PARAM The queried parameter key does apply to the provided event, but the corresponding value is not set.

◆ MV_Event_GetType()

MVLibExport MVEventType_t MV_Event_GetType ( MVEvent_t event )

Returns the type of a given event.

Parameters

[in] event is the event whose type is determined.

Returns: The MVEventType_t enum value corresponding to the type of event.

◆ MV_Event_Tuple_GetParameter()

MVLibExport MVCode_t MV_Event_Tuple_GetParameter	(	MVEvent_t	event,
		uint32_t	parameter,
		MVTuple_t *	pTuple
	)

Gets a parameter tuple of an event.

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

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

Parameters

[in]	event	is the event whose parameter is retrieved.
[in]	parameter	identifies the parameter that is retrieved; must match one of the parameters supported by events of the given type.
[out]	pTuple	points to a MVTuple_t which is then initialized to a copy of the desired parameter contained in the event.

Returns

MV_CODE_OK The parameter key applies to the provided event and the variable pointed to by pTuple has been initialized with its corresponding value.
MV_CODE_INV_HANDLE One or both of event or pTuple are NULL. Make sure event is properly initialized through a successful invocation of MV_TryGetEvent() and that pTuple points to an uninitialized writable variable.
MV_CODE_INV_OBJECT The opaque data structure referenced by event is not properly initialized.
MV_CODE_INV_PARAM The requested parameter key does not apply to the type of the provided event.

◆ MV_TryGetEvent()

MVLibExport MVCode_t MV_TryGetEvent	(	MVPlugin_t	handle,
		int32_t	timeout,
		MVEvent_t *	pEvent
	)

Attempts to retrieve a new event from this plug-in's event queue.

When the vision system publishes an event, it is enqueued to each plug-in's event queue. This function is used by the plug-ins to pop one event from this plug-in's event queue. If the latter contains at least one pending event, the function returns immediately and stores it into the variable of type MVEvent_t pointed to by the third argument. It lives until it is manually destroyed by way of call to MV_Event_Clear(), which becomes the plug-in's responsibility.

If the event queue is currently empty, the behavior is determined by the timeout argument. In case it is set to MV_TIME_NONE, the function immediately returns with error code MV_CODE_TIMEOUT. In case it is set to MV_TIME_INFINITE, the function blocks until a new event becomes available. It may also be set to a finite timeout (using macros MV_TIME_MILLISECOND(x) or MV_TIME_SECOND(x)) in which case it waits for at most the timeout's duration for an event to be enqueued. If so, it will pop it immediately; other it will return MV_CODE_TIMEOUT.

Parameters

[in]	handle	is the Communicator handle for the plug-in instance.
[in]	timeout	is measured in milliseconds; it is recommended to use the macros MV_TIME_MILLISECOND(x), MV_TIME_SECOND(x), or special values MV_TIME_NONE and MV_TIME_INFINITE, rather than specifying a numeric value directly.
[out]	pEvent	points to the event variable that is potentially initialized with a queued-up event.

Returns

MV_CODE_OK A new event was available and the variable pointed to by pEvent has been successfully initialized with it. It is the caller's responsibility to destroy the event using MV_Event_Clear() once they have finished processing it.
MV_CODE_INV_HANDLE The provided plug-in handle is not valid.
MV_CODE_ACCESS_DENIED The plug-in does not have the "monitor" access level needed to receive events. Ensure that the plug-in declares the "monitor" capability in MVInfo and is granted access to it when adding the plug-in instance.
MV_CODE_TIMEOUT No event from the vision system has been received within the specified timeout duration. Consequently, pEvent has not been initialized with an event and was set to NULL instead.

Functions

Detailed Description

Events

Function Documentation

◆ MV_Event_Clear()

◆ MV_Event_GetDataContainerDescriptor()

◆ MV_Event_GetParameter()

◆ MV_Event_GetType()

◆ MV_Event_Tuple_GetParameter()

◆ MV_TryGetEvent()