PIBIO_ENGINE_IDENTIFY_ALL_FN callback function (winbio_adapter.h)

Article
10/13/2021

Called by the Windows Biometric Framework to determine the identities of any people who are currently in camera frame.

Syntax

PIBIO_ENGINE_IDENTIFY_ALL_FN PibioEngineIdentifyAllFn;

HRESULT PibioEngineIdentifyAllFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [out]     PSIZE_T PresenceCount,
  [out]     PWINBIO_PRESENCE *PresenceArray
)
{...}

Parameters

[in, out] Pipeline

Pointer to the WINBIO_PIPELINE structure associated with the biometric unit performing the operation.

[out] PresenceCount

Address of a variable that receives the number of presences detected by the function.

[out] PresenceArray

Address of a variable that receives a pointer to an array of WINBIO_PRESENCE elements.

Return value

If the function succeeds, it returns S_OK. If the function fails, it must return one of the following HRESULT values to indicate the error.

Return code	Description
E_some_error	Any error code will cause the Biometric Service to log the error and ignore the camera frame.

Remarks

The biometric service calls this method after it sends a new frame of data to the engine adapter.

After processing the data frame, this function should return one WINBIO_PRESENCE element for each presence detected in the data frame.

In the event that the EngineAdapterIdentifyAll function can’t find any faces in frame, it returns an HRESULT of S_OK and sets the PresenceCount and PresenceArray return parameters to zero and NULL, respectively. In other words, a frame that doesn’t contain any human presences is not an error condition.

The only time EngineAdapterIdentifyAll should return an HRESULT other than S_OK is if it doesn’t want the bio service to use the frame to update the Presence Monitor state. This should be a rare occurrence. The engine adapter is responsible for allocating the array of WINBIO_PRESENCE elements it returns in the PresenceArray parameter. It must allocate this memory from the process heap by using the HeapAlloc function. After the array is created, it becomes the property of the Windows Biometric Framework. Because the Framework deallocates this memory after using it, your engine adapter must not attempt to deallocate the array or save a pointer to it. Failure to follow this rule will lead to heap corruption and possible crashes of the biometric service.

The values of the individual WINBIO_PRESENCE items in the PresenceArray will determine the events generated for client applications. See the discussion of the WINBIO_PRESENCE structure for details.

Requirements

Requirement	Value
Minimum supported client	Windows 10 [desktop apps only]
Minimum supported server	Windows Server 2016 [desktop apps only]
Target Platform	Windows
Header	winbio_adapter.h (include Winbio_adapter.h)

Share via