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

See also

WINBIO_ASYNC_RESULT

WinBioMonitorPresence

EngineAdapterIdentifyAll