Macros | Functions
mv_result_store.h File Reference

API function definitions for querying the result store. More...

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

Macros

#define MV_ResultList_foreach(list, result)
 Macro for iterating over the results in a list. More...
 

Functions

MVLibExport MVCode_t MV_GetResultById (MVPlugin_t handle, uint32_t resultId, MVResult_t *pResult)
 Retrieves a result from the result store based on its ID. More...
 
MVLibExport MVCode_t MV_GetResultListFiltered (MVPlugin_t handle, MVResultQuery_t query, MVResultList_t *pList)
 Retrieves a result list from the result store based on a query. More...
 
MVLibExport void MV_ResultList_Clear (MVResultList_t *pList)
 Destroys a result list. More...
 
MVLibExport size_t MV_ResultList_GetSize (MVResultList_t list)
 Gets the number of results in a result list. More...
 
MVLibExport MVResult_t MV_ResultList_Next (MVResultList_t list)
 Iterates over a result list. More...
 
MVLibExport MVCode_t MV_ResultList_Rewind (MVResultList_t list)
 Resets the built-in pointer to the beginning of a result list. More...
 
MVLibExport MVCode_t MV_ResultQuery_Init (MVResultQuery_t *pQuery)
 Initializes a result query of type MVResultQuery_t. More...
 
MVLibExport MVCode_t MV_ResultQuery_SetFilter (MVResultQuery_t query, uint32_t filter, MVValue_t value)
 Narrows a result query down by setting a filter criterion. More...
 
MVLibExport void MV_ResultQuery_Clear (MVResultQuery_t *pQuery)
 Destroys a result query. More...
 
MVLibExport MVCode_t MV_Result_GetParameter (MVResult_t result, uint32_t parameter, MVValue_t *pValue)
 Gets a parameter value of a given result. More...
 
MVLibExport MVCode_t MV_Result_Tuple_GetParameter (MVResult_t result, uint32_t parameter, MVTuple_t *pTuple)
 Gets a parameter tuple of a result. More...
 
MVLibExport MVCode_t MV_Result_GetDataContainerDescriptor (MVResult_t result, MVDataContainerDescriptor_t *pDescriptor)
 Gets a data container descriptor for the data components of a result. More...
 
MVLibExport void MV_Result_Clear (MVResult_t *pResult)
 Destroys a result. More...
 

Detailed Description

API function definitions for querying the result store.

Macro Definition Documentation

◆ MV_ResultList_foreach

#define MV_ResultList_foreach (   list,
  result 
)
Value:
MV_ResultList_Rewind(list); \
for ((result) = MV_ResultList_Next(list); (result); (result) = MV_ResultList_Next(list))

Macro for iterating over the results in a list.

Function Documentation

◆ MV_GetResultById()

MVLibExport MVCode_t MV_GetResultById ( MVPlugin_t  handle,
uint32_t  resultId,
MVResult_t *  pResult 
)

Retrieves a result from the result store based on its ID.

Note that the result store may only buffer a certain number of past results. This function returns MV_CODE_UNK_RESULT in case the requested result ID is not found in the result store.

Parameters
[in]handleis the Communicator handle for the plug-in instance.
[in]resultIdis the result ID for which the result is retrieved.
[out]pResultpoints to the uninitialized result handle which is initialized with the requested result.
Returns
  • MV_CODE_OK The result for the specified result ID has been successfully retrieved and pResult has been initialized with it.
  • MV_CODE_INV_HANDLE The provided plug-in handle is not valid.
  • MV_CODE_INV_VALUE The provided pointer pResult is NULL.
  • MV_CODE_TIMEOUT The retrieval of the result from the vision system timed out. The vision system may not be running at all.
  • MV_CODE_UNK_RESULT The result for the desired result ID could not be found in the vision system's result store. The result may not be ready yet or it may already have been dropped from the result buffer.
  • MV_CODE_PLUGIN_NOT_REGISTERED The plug-in is not currently registered. This indicates that MV_GetResultById has been called from a self-spawned thread and outside of its allowed plug-in lifetime.
  • MV_CODE_OUT_OF_MEM The result could not be stored because the system is out of memory.
  • MV_CODE_FAILED An unknown problem has occurred.

◆ MV_GetResultListFiltered()

MVLibExport MVCode_t MV_GetResultListFiltered ( MVPlugin_t  handle,
MVResultQuery_t  query,
MVResultList_t *  pList 
)

Retrieves a result list from the result store based on a query.

Note that the result store may only keep a certain number of past results. This may negatively impact the vision system's performance when the query is not very specific and the vision system supports a large result store.

The list can be narrowed down through the query argument. The query must be initialized by way of MV_ResultQuery_Init() and various filtering criteria may be specified through MV_ResultQuery_SetFilter() prior to calling this function. The same query can be reused multiple times before destroying it using MV_ResultQuery_Clear().

Each call to MV_GetResultListFiltered() has to be balanced by a call to MV_ResultList_Clear().

Parameters
[in]handleis the Communicator handle for the plug-in instance.
[in]queryspecifies the criteria according to which the list is filtered.
[out]pListpoints to the result list variable that is initialized with the filtered list.
Returns
  • MV_CODE_OK The result list matching the query has been successfully retrieved and pList has been initialized with it.
  • MV_CODE_INV_HANDLE The provided plug-in handle is not valid.
  • MV_CODE_INV_VALUE The provided pointer pList is NULL.
  • MV_CODE_TIMEOUT The retrieval of the result list 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_GetResultListFiltered has been called from a self-spawned thread and outside of its allowed plug-in lifetime.
  • MV_CODE_OUT_OF_MEM The result could not be stored because the system is out of memory.
  • MV_CODE_FAILED An unknown problem has occurred.

◆ MV_Result_Clear()

MVLibExport void MV_Result_Clear ( MVResult_t *  pResult)

Destroys a result.

Each copy of a result made using MV_GetResultById() must be balanced by a call to MV_Result_Clear().

Remarks
Note that result handles obtained by iterating over a result list using MV_ResultList_Next() or the MV_ResultList_foreach() macro must not be destroyed.
Parameters
[in,out]pResultpoints to the handle to the result that is destroyed.

◆ MV_Result_GetDataContainerDescriptor()

MVLibExport MVCode_t MV_Result_GetDataContainerDescriptor ( MVResult_t  result,
MVDataContainerDescriptor_t *  pDescriptor 
)

Gets a data container descriptor for the data components of a result.

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 specified result. 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]resultis the handle to the result that is queried.
[out]pDescriptorpoints 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_Result_GetParameter()

MVLibExport MVCode_t MV_Result_GetParameter ( MVResult_t  result,
uint32_t  parameter,
MVValue_t *  pValue 
)

Gets a parameter value of a given result.

Initializes a new MVValue_t with a copy of the requested parameter. It is the caller's responsibility to destroy this copy by way of MV_Value_Clear().

The following parameters are available (followed by the type of the correspondingly retrieved MVValue_t):

These parameters and the semantics of their corresponding values mirror those which are available for ResultReady events.

Remarks
Note that this function cannot be used to access the result content as the parameter is tuple-valued; use MV_Result_Tuple_GetParameter() for this purpose.
Parameters
[in]resultis the handle to the result that is queried.
[in]parameteris one of the above MV_PARAM_* defines.
[out]pValuepoints to the value handle that is initialized with a copy of the value of the queried parameter.
Returns
  • MV_CODE_OK The value corresponding to the specified parameter key was successfully used to initialize the value pointed to by pValue.
  • MV_CODE_INV_HANDLE The provided result is not valid.
  • MV_CODE_INV_VALUE The pointer pValue is NULL.
  • MV_CODE_UNK_PARAM The provided parameter key does not match any parameters which apply to results.
  • MV_CODE_UNSET_PARAM The queried parameter key does apply to the provided result, but the corresponding value is not set.

◆ MV_Result_Tuple_GetParameter()

MVLibExport MVCode_t MV_Result_Tuple_GetParameter ( MVResult_t  result,
uint32_t  parameter,
MVTuple_t *  pTuple 
)

Gets a parameter tuple of a result.

This function works analogous to MV_Result_GetParameter() but is used to get parameter tuples rather than individual values. Currently, only the result content is tuple-valued and may be accessed through the parameter key MV_PARAM_RESULT_CONTENT.

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

Parameters
[in]resultis the handle to the result that is queried.
[in]parameteridentifies the parameter which is retrieved. Currently, it must equal MV_PARAM_RESULT_CONTENT.
[out]pTuplepoints to a MVTuple_t which is then initialized to a copy of the desired parameter contained in the result.
Returns

◆ MV_ResultList_Clear()

MVLibExport void MV_ResultList_Clear ( MVResultList_t *  pList)

Destroys a result list.

Each call to MV_GetResultListFiltered() has to be balanced by a call to MV_ResultList_Clear().

Parameters
[in,out]pListpoints to the result list handle that is destroyed.

◆ MV_ResultList_GetSize()

MVLibExport size_t MV_ResultList_GetSize ( MVResultList_t  list)

Gets the number of results in a result list.

Parameters
[in]listis the handle to the result list which is queried.
Returns
The number of results in the list.

◆ MV_ResultList_Next()

MVLibExport MVResult_t MV_ResultList_Next ( MVResultList_t  list)

Iterates over a result list.

Result lists have a built-in pointer to the "current" result. This function returns a handle to the currently pointed-to result and advances the pointer by one. If the end of the result list is reached, the returned result 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 result list is destroyed and calling MV_Result_Clear() on them is undefined behavior.
Parameters
[in]listis the handle to the result list to iterate over.
Returns
A non-owning handle to the currently pointed-to result in the list.

◆ MV_ResultList_Rewind()

MVLibExport MVCode_t MV_ResultList_Rewind ( MVResultList_t  list)

Resets the built-in pointer to the beginning of a result list.

Parameters
[in]listis the handle to the result list whose internal pointer should be reset.
Returns

◆ MV_ResultQuery_Clear()

MVLibExport void MV_ResultQuery_Clear ( MVResultQuery_t *  pQuery)

Destroys a result query.

Each call to MV_ResultQuery_Init() has to be balanced by a call to MV_ResultQuery_Clear(). Clearing the query does not clear any result lists which may have been obtained through it; these need to be cleared separately using MV_ResultList_Clear().

Parameters
[in,out]pQuerypoints to the query that is destroyed.

◆ MV_ResultQuery_Init()

MVLibExport MVCode_t MV_ResultQuery_Init ( MVResultQuery_t *  pQuery)

Initializes a result query of type MVResultQuery_t.

Each call to MV_ResultQuery_Init() has to be balanced by a call to MV_ResultQuery_Clear().

Parameters
[out]pQuerypoints to the query variable which is initialized.
Returns
  • MV_CODE_OK The variable pointed-to by pQuery has been successfully initialized with a query matching any result.
  • MV_CODE_INV_HANDLE The provided pointer pQuery is NULL.
  • MV_CODE_OUT_OF_MEM The result could not be stored because the system is out of memory.
  • MV_CODE_FAILED An unknown problem has occurred.

◆ MV_ResultQuery_SetFilter()

MVLibExport MVCode_t MV_ResultQuery_SetFilter ( MVResultQuery_t  query,
uint32_t  filter,
MVValue_t  value 
)

Narrows a result query down by setting a filter criterion.

Setting a filter criterion using this function has the effect of restricting the results which are included in the list when passing the query to MV_GetResultListFiltered() to only those results whose parameters match the filter. The function can be called multiple times on the same query for different filter parameters to refine it to only those results matching all of the filter criteria.

The following values for the filter argument are applicable:

  • MV_PARAM_RECIPE_ID : Only keep results of jobs executing the recipe whose recipe ID equals the scalar string value.
  • MV_PARAM_JOB_ID : Only keep results of jobs whose job ID equals the scalar UInt32 value.
  • MV_PARAM_MEAS_ID : Only keep results of jobs whose measurement ID equals the scalar string value.
  • MV_PARAM_PART_ID : Only keep results of jobs whose part ID equals the scalar string value.
  • MV_PARAM_RESULT_STATE : Only keep results whose result state's numeric representation (according to the enum MVResultState_t) equals the scalar UInt32 value.
Parameters
[in]queryis the query that is refined by the filter.
[in]filteris one of the filter criteria listed above.
[in]valueis the value which the filtering parameter must be equal to in order for the result to be included in the list. Its value type and data type must be chosen appropriately as documented above.
Returns
MV_ResultList_Rewind
MVLibExport MVCode_t MV_ResultList_Rewind(MVResultList_t list)
Resets the built-in pointer to the beginning of a result list.
MV_ResultList_Next
MVLibExport MVResult_t MV_ResultList_Next(MVResultList_t list)
Iterates over a result list.