API function definitions for data containers. More...

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

Macros
#define	MV_DataContainerDescriptor_foreach(containerDesc, componentDesc)
	Macro for iterating over the data component descriptors in a data container descriptor. More...

#define	MV_DataContainer_foreach(container, component)
	Macro for iterating over the data components of a structured data container. More...

Functions
MVLibExport MVCode_t	MV_DataContainerDescriptor_Init (MVDataContainerDescriptor_t *pDescriptor, MVDataContainerType_t type)
	Initializes a new data container descriptor. More...

MVLibExport MVCode_t	MV_DataContainerDescriptor_AddComponent (MVDataContainerDescriptor_t descriptor, MVDataComponentDescriptor_t component)
	Adds a data component descriptor to a data container descriptor. More...

MVLibExport void	MV_DataContainerDescriptor_Clear (MVDataContainerDescriptor_t *pDescriptor)
	Destroys a data container descriptor. More...

MVLibExport MVCode_t	MV_DataContainerDescriptor_SetType (MVDataContainerDescriptor_t descriptor, MVDataContainerType_t type)
	Sets the type of a requested data container. More...

MVLibExport MVDataContainerType_t	MV_DataContainerDescriptor_GetType (MVDataContainerDescriptor_t descriptor)
	Gets the type of a requested data container. More...

MVLibExport size_t	MV_DataContainerDescriptor_GetSize (MVDataContainerDescriptor_t descriptor)
	Gets the number of data component descriptors contained in the given data container descriptor. More...

MVLibExport MVDataComponentDescriptor_t	MV_DataContainerDescriptor_Next (MVDataContainerDescriptor_t descriptor)
	Iterates over the data component descriptors in a data container descriptor. More...

MVLibExport MVCode_t	MV_DataContainerDescriptor_Rewind (MVDataContainerDescriptor_t descriptor)
	Resets the built-in pointer to the beginning of a data container descriptor. More...

MVLibExport MVCode_t	MV_FetchDataContainer (MVPlugin_t handle, MVDataContainerDescriptor_t containerDesc, MVDataContainer_t *pContainer)
	Obtains a data container from the vision system. More...

MVLibExport void	MV_DataContainer_Clear (MVDataContainer_t *pContainer)
	Destroys a data container. More...

MVLibExport MVDataContainerType_t	MV_DataContainer_GetType (MVDataContainer_t container)
	Gets the type of a data container. More...

MVLibExport size_t	MV_DataContainer_GetSize (MVDataContainer_t container)
	Gets the number of data components contained in the given structured data container. More...

MVLibExport MVDataComponent_t	MV_DataContainer_Next (MVDataContainer_t container)
	Iterates over the data components of a given structured data container. More...

MVLibExport MVCode_t	MV_DataContainer_Rewind (MVDataContainer_t container)
	Resets the built-in pointer to the beginning of a structured data container. More...

Detailed Description

API function definitions for data containers.

Macro Definition Documentation

◆ MV_DataContainer_foreach

#define MV_DataContainer_foreach	(	container,
		component
	)

Value:

MV_DataContainer_Rewind(container); \

for ((component) = MV_DataContainer_Next(container); (component); (component) = MV_DataContainer_Next(container))

Macro for iterating over the data components of a structured data container.

◆ MV_DataContainerDescriptor_foreach

#define MV_DataContainerDescriptor_foreach	(	containerDesc,
		componentDesc
	)

Value:

  MV_DataContainerDescriptor_Rewind(containerDesc);                                                                         \
  for ((componentDesc) = MV_DataContainerDescriptor_Next(containerDesc); (componentDesc);                                   \
       (componentDesc) = MV_DataContainerDescriptor_Next(containerDesc))

Macro for iterating over the data component descriptors in a data container descriptor.

Function Documentation

◆ MV_DataContainer_Clear()

MVLibExport void MV_DataContainer_Clear ( MVDataContainer_t * pContainer )

Destroys a data container.

Each handle to a data container obtained through MV_FetchDataContainer() must be balanced by a call to MV_DataContainer_Clear().

Parameters

[in,out] pContainer points to the handle to the data container that is destroyed.

◆ MV_DataContainer_GetSize()

MVLibExport size_t MV_DataContainer_GetSize ( MVDataContainer_t container )

Gets the number of data components contained in the given structured data container.

Parameters

[in] container is the handle to the structured data container that is queried.

Returns: The number of data components of the queried structured data container, or 0 if the data container is not of the "structured" type.

◆ MV_DataContainer_GetType()

MVLibExport MVDataContainerType_t MV_DataContainer_GetType ( MVDataContainer_t container )

Gets the type of a data container.

Presently, only "structured" data containers are supported. See MVDataContainerType_t for details.

Parameters

[in] container is the handle to the data container that is queried.

Returns: The enumerator of type MVDataContainerType_t corresponding to the type of the data container.

◆ MV_DataContainer_Next()

MVLibExport MVDataComponent_t MV_DataContainer_Next ( MVDataContainer_t container )

Iterates over the data components of a given structured data container.

Structured data containers have a built-in pointer to the "current" data component. This function returns a handle to the currently pointed-to data component and advances the pointer by one. If the end of the data container is reached, the returned data component handle will evaluate to false if coerced in a boolean context such as the conditional expression of an if or while statement.

Remarks: Note that the handles returned by the function are non-owning. They remain valid only until the data container is destroyed.

Parameters

[in] container is the handle to the structured data container that is iterated over.

Returns: A non-owning handle to the currently pointed-to data component.

◆ MV_DataContainer_Rewind()

MVLibExport MVCode_t MV_DataContainer_Rewind ( MVDataContainer_t container )

Resets the built-in pointer to the beginning of a structured data container.

Parameters

[in] container is the handle to the structured data container whose internal pointer should be reset.

Returns

MV_CODE_OK The internal pointer has been reset.
MV_CODE_INV_HANDLE The provided data container is not valid.
MV_CODE_INV_DATA_CONTAINER_TYPE The provided data container is not of the "structured" type.

◆ MV_DataContainerDescriptor_AddComponent()

MVLibExport MVCode_t MV_DataContainerDescriptor_AddComponent	(	MVDataContainerDescriptor_t	descriptor,
		MVDataComponentDescriptor_t	component
	)

Adds a data component descriptor to a data container descriptor.

This function can be used to append a copy of an existing data component descriptor to a data container descriptor. This may be used in order to aggregate multiple component descriptors into a single data container descriptor in order to defer fetching all those data components "in bulk" as a single data container. It may also be useful to duplicate data component descriptors within the same data container descriptor in order to request the same data component in different formats (e.g. the original image and a scaled-down PNG thumbnail).

Parameters

[in]	descriptor	is the handle to the data container descriptor to which the component should be added.
[in]	component	is a handle to a MVDataComponentDescriptor_t. The descriptor referenced by this handle is copied and appended to the container `descriptor`.

Returns

MV_CODE_OK The component descriptor was successfully appended.
MV_CODE_INV_HANDLE The provided data container descriptor is not valid.
MV_CODE_INV_VALUE The provided data component descriptor is not valid.

◆ MV_DataContainerDescriptor_Clear()

MVLibExport void MV_DataContainerDescriptor_Clear ( MVDataContainerDescriptor_t * pDescriptor )

Destroys a data container descriptor.

Each handle to a data container descriptor created through MV_DataContainerDescriptor_Init() or obtained through MV_Event_GetDataContainerDescriptor() or MV_Result_GetDataContainerDescriptor(), respectively, must be destroyed by a call to MV_DataContainerDescriptor_Clear().

Parameters

[in,out] pDescriptor points to the handle to the data container descriptor that is destroyed.

◆ MV_DataContainerDescriptor_GetSize()

MVLibExport size_t MV_DataContainerDescriptor_GetSize ( MVDataContainerDescriptor_t descriptor )

Gets the number of data component descriptors contained in the given data container descriptor.

Parameters

[in] descriptor is the handle to the data container descriptor that is queried.

Returns: The number of data component descriptors of the queried data container descriptor.

◆ MV_DataContainerDescriptor_GetType()

MVLibExport MVDataContainerType_t MV_DataContainerDescriptor_GetType ( MVDataContainerDescriptor_t descriptor )

Gets the type of a requested data container.

Presently, only "structured" data containers are supported. See MVDataContainerType_t for details.

Parameters

[in] descriptor is the handle to the data container descriptor that is queried.

Returns: The enumerator of type MVDataContainerType_t corresponding to the type of the data container which is to be fetched.

◆ MV_DataContainerDescriptor_Init()

MVLibExport MVCode_t MV_DataContainerDescriptor_Init	(	MVDataContainerDescriptor_t *	pDescriptor,
		MVDataContainerType_t	type
	)

Initializes a new data container descriptor.

Creates an empty data container descriptor which may subsequently be filled with component descriptors using MV_DataContainerDescriptor_AddComponent(). This function is intended to be used when only a subset of data components that are available as part of a result are of interest, or to build a new data container descriptor which combines components from multiple results; otherwise data container descriptors may be obtained through MV_Event_GetDataContainerDescriptor() or MV_Result_GetDataContainerDescriptor(), respectively.

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

Parameters

[out]	pDescriptor	points to the handle of the data container descriptor that is initialized.
[in]	type	specifies which type of data container should be fetched. Currently, only "structured" data containers are supported.

Returns

MV_CODE_OK The descriptor was successfully initialized.
MV_CODE_INV_HANDLE The pointer pDescriptor is NULL. Provide a pointer to a variable of type MVDataContainerDescriptor_t which is to be initialized.
MV_CODE_INV_DATA_CONTAINER_TYPE The specified data container type is not supported.

◆ MV_DataContainerDescriptor_Next()

MVLibExport MVDataComponentDescriptor_t MV_DataContainerDescriptor_Next ( MVDataContainerDescriptor_t descriptor )

Iterates over the data component descriptors in a data container descriptor.

Data container descriptors have a built-in pointer to the "current" data component descriptor. This function returns a handle to the currently pointed-to data component descriptor and advances the pointer by one. If the end of the data container descriptor is reached, the returned data component descriptor handle will evaluate to false if coerced in a boolean context such as the conditional expression of an if or while statement.

Remarks: Note that the handles returned by the function are non-owning. They remain valid only until the data container descriptor is destroyed.

Parameters

[in] descriptor is the handle to the data container descriptor that is iterated over.

Returns: A non-owning handle to the currently pointed-to data component descriptor in the data container descriptor.

◆ MV_DataContainerDescriptor_Rewind()

MVLibExport MVCode_t MV_DataContainerDescriptor_Rewind ( MVDataContainerDescriptor_t descriptor )

Resets the built-in pointer to the beginning of a data container descriptor.

Parameters

[in] descriptor is the handle to the data container descriptor whose internal pointer should be reset.

Returns

MV_CODE_OK The internal pointer has been reset.
MV_CODE_INV_HANDLE The provided data container descriptor is not valid.

◆ MV_DataContainerDescriptor_SetType()

MVLibExport MVCode_t MV_DataContainerDescriptor_SetType	(	MVDataContainerDescriptor_t	descriptor,
		MVDataContainerType_t	type
	)

Sets the type of a requested data container.

Presently, only "structured" data containers are supported. See MVDataContainerType_t for details.

Parameters

[in]	descriptor	is the handle to the data container descriptor whose type is to be changed.
[in]	type	is an enumerator of type MVDataContainerType_t corresponding to the type of the data container which is to be fetched.

Returns

MV_CODE_OK The type was successfully changed.
MV_CODE_INV_HANDLE The provided data container descriptor is not valid.
MV_CODE_INV_DATA_CONTAINER_TYPE The specified data container type is not supported.

◆ MV_FetchDataContainer()

MVLibExport MVCode_t MV_FetchDataContainer	(	MVPlugin_t	handle,
		MVDataContainerDescriptor_t	containerDesc,
		MVDataContainer_t *	pContainer
	)

Obtains a data container from the vision system.

This function requests a data container from the vision system based on the provided data container descriptor. It will block the current thread until a response has been received. The resulting data container will contain one data component per data component descriptor. The vision system will try to cater to the requested type and parameters specified in the corresponding data component descriptors. If this is not possible to satisfy, e.g., because a requested data component is no longer available inside the vision system or because the conversion to the requested data component type is either not possible or not supported, a data component of type "Error" will take its place in the data container. See mv_data_component.h for function to extract information from data containers and components.

Remarks: Each call to MV_FetchDataContainer() has to be balanced by a call to MV_DataContainer_Clear().

Parameters

[in]	handle	is the Communicator handle for the plug-in instance.
[in]	request	is the Communicator handle for the plug-in instance.
[out]	pContainer	points to the uninitialized recipe list handle that is initialized with the current recipe list.

Returns

MV_CODE_OK The data container has been successfully fetched and pContainer has been initialized with it.
MV_CODE_INV_HANDLE The provided plug-in handle is not valid.
MV_CODE_INV_VALUE The provided pointer pContainer is NULL.
MV_CODE_TIMEOUT The retrieval of the data container from 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_FetchDataContainer() has been called from a self-spawned thread and outside of its allowed plug-in lifetime.
MV_CODE_OUT_OF_MEM The data container could not be stored because the system is out of memory.
MV_CODE_FAILED An unknown problem has occurred.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ MV_DataContainer_foreach

◆ MV_DataContainerDescriptor_foreach

Function Documentation

◆ MV_DataContainer_Clear()

◆ MV_DataContainer_GetSize()

◆ MV_DataContainer_GetType()

◆ MV_DataContainer_Next()

◆ MV_DataContainer_Rewind()

◆ MV_DataContainerDescriptor_AddComponent()

◆ MV_DataContainerDescriptor_Clear()

◆ MV_DataContainerDescriptor_GetSize()

◆ MV_DataContainerDescriptor_GetType()

◆ MV_DataContainerDescriptor_Init()

◆ MV_DataContainerDescriptor_Next()

◆ MV_DataContainerDescriptor_Rewind()

◆ MV_DataContainerDescriptor_SetType()

◆ MV_FetchDataContainer()