WINBIO_PRESENCE structure
Contains information about the presence of an individual whose presence is being monitored.
Syntax
typedef struct _WINBIO_PRESENCE {
WINBIO_BIOMETRIC_TYPE Factor;
WINBIO_BIOMETRIC_SUBTYPE SubFactor;
HRESULT Status;
WINBIO_REJECT_DETAIL RejectDetail;
WINBIO_IDENTITY Identity;
ULONGLONG TrackingId;
WINBIO_PROTECTION_TICKET Ticket;
WINBIO_PRESENCE_PROPERTIES Properties;
} WINBIO_PRESENCE, *PWINBIO_PRESENCE;
Members
-
Factor
-
The biometric factor used to monitor the presence of the individual.
-
SubFactor
-
The biometric subfactor qualifier for the biometric factor used to monitor the presence of the individual.
-
Status
-
The status of the identification procedure for the individual.
-
RejectDetail
-
Additional information about the failure to recognize an individual, including feedback that explains how to correct the failure.
-
Identity
-
The identity of the individual whose presence is being monitored, once that individual has been identified.
-
TrackingId
-
An integer that is generated by the adapter and uniquely identifies the individual. The tracking identifier that the adapter assigns to a particular individual is guaranteed to be constant as long as that person remains in the camera frame.
-
Ticket
-
Reserved. Set to 0 by the adapter.
-
Properties
-
Factor-specific information about the position of an individual.
Remarks
The EngineAdapterIdentifyAll function creates an array of WINBIO_PRESENCE structures and sends this array to the biometric service. The biometric service uses the array to update its internal model of humans near the computer.
Depending on the results of this update, the biometric service may generate a WINBIO_ASYNC_RESULT structure for the WinBioMonitorPresence function for any clients with active presence monitors. The WINBIO_ASYNC_RESULT.Operation member of the structure contains WINBIO_OPERATION_MONITOR_PRESENCE, and the WINBIO_ASYNC_RESULT.Parameters.MonitorPresence.ChangeType member provides additional information about the state of the individual.
When an individual that the engine adapter associates with a particular tracking identifier appears in the input stream for the first time, the biometric service generates a client-side WINBIO_ASYNC_RESULT structure where the WINBIO_ASYNC_RESULT.Parameters.MonitorPresence.ChangeType member is WINBIO_CHANGE_TYPE_ARRIVAL. This structure is sent to your application callback function or application message queue before any other WINBIO_ASYNC_RESULT structures where the WINBIO_ASYNC_RESULT.Parameters.MonitorPresence.PresenceArray includes a WINBIO_PRESENCE structure with the same value for WINBIO_PRESENCE.TrackingId.
The following combinations of values in the array of WINBIO_PRESENCE structures that the WINBIO_ASYNC_RESULT.Parameters.MonitorPresence.PresenceArray member indicate specific kinds of changes in the state of an individual.
When an individual is visible in the camera frame, but the engine is still trying to identify the individual, the members of the WINBIO_PRESENCE structure have the values in the following table.
Member Value TrackingId An integer that identifies the individual to the engine. Status S_OK Identity.Type WINBIO_ID_TYPE_NULL In this case, the biometric service extends the expiry time for the individual, and does not generate a client-side WINBIO_ASYNC_RESULT structure for the tracking identifier where the WINBIO_ASYNC_RESULT.Parameters.MonitorPresence.ChangeType member is WINBIO_CHANGE_TYPE_RECOGNIZE.
The first time that a WINBIO_ASYNC_RESULT structure includes WINBIO_PRESENCE structure where the Status member is S_OK and the Identity.Type member is WINBIO_ID_TYPE_NULL after one or more WINBIO_ASYNC_RESULT structures included a WINBIO_PRESENCE structure with a Status member of WINBIO_E_BAD_CAPTURE, the presence monitor generates a single WINBIO_ASYNC_RESULT structure for the tracking identifier where the WINBIO_ASYNC_RESULT.Parameters.MonitorPresence.ChangeType member is WINBIO_CHANGE_TYPE_TRACK. This WINBIO_ASYNC_RESULT structure where the WINBIO_ASYNC_RESULT.Parameters.MonitorPresence.ChangeType member is WINBIO_CHANGE_TYPE_TRACK informs the client that the problem that caused the WINBIO_E_BAD_CAPTURE error has resolved. For more information about the circumstances where a WINBIO_PRESENCE structure has Status member of WINBIO_E_BAD_CAPTURE, see the description about how the engine adapter provides feedback to the user to correct recognition failures later in these Remarks.
When an individual is visible in the camera frame, but the engine is still trying to identify the individual and wants to provide feedback to the user about how to correct a recognition failure, the members of the WINBIO_PRESENCE structure have the values in the following table.
Member Value TrackingId An integer that identifies the individual to the engine. Status WINBIO_E_BAD_CAPTURE Identity.Type WINBIO_ID_TYPE_NULL Properties.FacialFeatures.BoundingBox, if the value of Factor is WINBIO_TYPE_FACIAL_FEATURES The location of the face of the individual within the camera frame. Properties.Iris.BoundingBox, if the value of Factor is WINBIO_TYPE_IRIS The location of the iris or irises of the individual within the camera frame. In this case, the biometric service extends the expiry time for the individual and generates a WINBIO_ASYNC_RESULT structure for the tracking identifier where the WINBIO_ASYNC_RESULT.Parameters.MonitorPresence.ChangeType member is WINBIO_CHANGE_TYPE_TRACK.
When an individual is visible in the camera frame, and the engine adapter determines the identity of the individual, the members of the WINBIO_PRESENCE structure have the values in the following table.
Member Value TrackingId An integer that identifies the individual to the engine. Status S_OK Identity.Type WINBIO_ID_TYPE_SID Identity.Value.AccountSid The security identifier (SID) of the individual. In this case, the biometric service associates the tracking identifier with the SID for the individual and generates a client-side WINBIO_ASYNC_RESULT structure for the tracking identifier where the WINBIO_ASYNC_RESULT.Parameters.MonitorPresence.ChangeType member is WINBIO_CHANGE_TYPE_RECOGNIZE. The biometric service does not generate additional client-side WINBIO_ASYNC_RESULT structures for the tracking identifier unless the individual leaves the camera frame.
When an individual is visible in the camera frame, but the engine adapter determines for certain that the individual is not enrolled, the members of the WINBIO_PRESENCE structure have the values in the following table.
Member Value TrackingId An integer that identifies the individual to the engine. Status WINBIO_E_UNKNOWN_ID Identity.Type WINBIO_ID_TYPE_NULL In this case, the biometric service associates the tracking identifier of the individual with an identity of UNKNOWN, and generates a client-side WINBIO_ASYNC_RESULT structure for the tracking identifier where the WINBIO_ASYNC_RESULT.Parameters.MonitorPresence.ChangeType member is WINBIO_CHANGE_TYPE_RECOGNIZE. The biometric service does not generate additional client-side WINBIO_ASYNC_RESULT structures for the tracking identifier unless the individual leaves the camera frame.
When an individual that the engine adapter associates with a particular tracking identifier leaves the camera frame and stops appearing in the values that the EngineAdapterIdentifyAll function returns, the tracking identifier eventually expires. When the tracking identifier expires, the biometric service generates a client-side WINBIO_ASYNC_RESULT structure where the WINBIO_ASYNC_RESULT.Parameters.MonitorPresence.ChangeType member is WINBIO_CHANGE_TYPE_DEPART. The engine adapter can prevent the biometric service from generating this structure with the WINBIO_CHANGE_TYPE_DEPART value by including a WINBIO_PRESENCE structure in the array that EngineAdapterIdentifyAll returns, where the WINBIO_PRESENCE.Status member is S_OK and the WINBIO_PRESENCE.Identity.Type member is WINBIO_ID_TYPE_NULL as described earlier in these Remarks. This action extends the expiry time for the tracking identifier without causing any client-side activity.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client |
Windows 10 [desktop apps only] |
| Minimum supported server |
Windows Server 2016 [desktop apps only] |
| Header |
|