WINBIO_ASYNC_RESULT structure (winbio.h)
The WINBIO_ASYNC_RESULT structure contains the results of an asynchronous operation.
Syntax
typedef struct _WINBIO_ASYNC_RESULT {
WINBIO_SESSION_HANDLE SessionHandle;
WINBIO_OPERATION_TYPE Operation;
ULONGLONG SequenceNumber;
LONGLONG TimeStamp;
HRESULT ApiStatus;
WINBIO_UNIT_ID UnitId;
PVOID UserData;
union {
struct {
BOOLEAN Match;
WINBIO_REJECT_DETAIL RejectDetail;
} Verify;
struct {
WINBIO_IDENTITY Identity;
WINBIO_BIOMETRIC_SUBTYPE SubFactor;
WINBIO_REJECT_DETAIL RejectDetail;
} Identify;
struct {
WINBIO_BIOMETRIC_SUBTYPE SubFactor;
} EnrollBegin;
struct {
WINBIO_REJECT_DETAIL RejectDetail;
} EnrollCapture;
struct {
WINBIO_IDENTITY Identity;
BOOLEAN IsNewTemplate;
} EnrollCommit;
struct {
WINBIO_IDENTITY Identity;
SIZE_T SubFactorCount;
WINBIO_BIOMETRIC_SUBTYPE *SubFactorArray;
} EnumEnrollments;
struct {
PWINBIO_BIR Sample;
SIZE_T SampleSize;
WINBIO_REJECT_DETAIL RejectDetail;
} CaptureSample;
struct {
WINBIO_IDENTITY Identity;
WINBIO_BIOMETRIC_SUBTYPE SubFactor;
} DeleteTemplate;
struct {
WINBIO_PROPERTY_TYPE PropertyType;
WINBIO_PROPERTY_ID PropertyId;
WINBIO_IDENTITY Identity;
WINBIO_BIOMETRIC_SUBTYPE SubFactor;
SIZE_T PropertyBufferSize;
PVOID PropertyBuffer;
} GetProperty;
struct {
WINBIO_PROPERTY_TYPE PropertyType;
WINBIO_PROPERTY_ID PropertyId;
WINBIO_IDENTITY Identity;
WINBIO_BIOMETRIC_SUBTYPE SubFactor;
SIZE_T PropertyBufferSize;
PVOID PropertyBuffer;
} SetProperty;
struct {
WINBIO_EVENT Event;
} GetEvent;
struct {
WINBIO_COMPONENT Component;
ULONG ControlCode;
ULONG OperationStatus;
PUCHAR SendBuffer;
SIZE_T SendBufferSize;
PUCHAR ReceiveBuffer;
SIZE_T ReceiveBufferSize;
SIZE_T ReceiveDataSize;
} ControlUnit;
struct {
SIZE_T BspCount;
WINBIO_BSP_SCHEMA *BspSchemaArray;
} EnumServiceProviders;
struct {
SIZE_T UnitCount;
WINBIO_UNIT_SCHEMA *UnitSchemaArray;
} EnumBiometricUnits;
struct {
SIZE_T StorageCount;
WINBIO_STORAGE_SCHEMA *StorageSchemaArray;
} EnumDatabases;
struct {
BOOLEAN Match;
WINBIO_REJECT_DETAIL RejectDetail;
WINBIO_PROTECTION_TICKET Ticket;
} VerifyAndReleaseTicket;
struct {
WINBIO_IDENTITY Identity;
WINBIO_BIOMETRIC_SUBTYPE SubFactor;
WINBIO_REJECT_DETAIL RejectDetail;
WINBIO_PROTECTION_TICKET Ticket;
} IdentifyAndReleaseTicket;
struct {
ULONGLONG SelectorValue;
} EnrollSelect;
struct {
WINBIO_PRESENCE_CHANGE ChangeType;
SIZE_T PresenceCount;
WINBIO_PRESENCE *PresenceArray;
} MonitorPresence;
struct {
WINBIO_IDENTITY Identity;
WINBIO_PROTECTION_POLICY Policy;
} GetProtectionPolicy;
struct {
WINBIO_EXTENDED_UNIT_STATUS ExtendedStatus;
} NotifyUnitStatusChange;
} Parameters;
} WINBIO_ASYNC_RESULT, *PWINBIO_ASYNC_RESULT;
Members
SessionHandle
Handle of an asynchronous session started by calling the WinBioAsyncOpenSession function or the WinBioAsyncOpenFramework function.
Operation
Type of the asynchronous operation. For more information, see WINBIO_OPERATION_TYPE Constants.
SequenceNumber
Sequence number of the asynchronous operation. The integers are assigned sequentially for each operation in a biometric session, starting at one (1). For any session, the open operation is always assigned the first sequence number and the close operation is assigned the last sequence number. If your application queues multiple operations, you can use sequence numbers to perform error handling. For example, you can ignore operation results until a specific sequence number is sent to the application.
TimeStamp
System date and time at which the biometric operation began. For more information, see the GetSystemTimeAsFileTime function.
ApiStatus
Error code returned by the operation.
UnitId
The numeric unit identifier of the biometric unit that performed the operation.
UserData
Address of an optional buffer supplied by the caller. The buffer is not modified by the framework or the biometric unit. Your application can use the data to help it determine what actions to perform upon receipt of the completion notice or to maintain additional information about the requested operation.
Parameters
Union that encloses nested structures that contain additional information about the success or failure of asynchronous operations begun by the client application.
Parameters.Verify
Contains the results of an asynchronous call to WinBioVerify.
Parameters.Verify.Match
Specifies whether the captured sample matched the user identity.
Parameters.Verify.RejectDetail
Additional information about verification failure. For more information, see Remarks.
Parameters.Identify
Contains the results of an asynchronous call to WinBioIdentify.
Parameters.Identify.Identity
GUID or SID of the user providing the biometric sample.
Parameters.Identify.SubFactor
Sub-factor associated with the biometric sample. For more information, see Remarks.
Parameters.Identify.RejectDetail
Additional information about the failure, if any, to capture and identify a biometric sample. For more information, see Remarks.
Parameters.EnrollBegin
Contains the results of an asynchronous call to WinBioEnrollBegin.
Parameters.EnrollBegin.SubFactor
Additional information about the enrollment. For more information, see Remarks.
Parameters.EnrollCapture
Contains the results of an asynchronous call to WinBioEnrollCapture.
Parameters.EnrollCapture.RejectDetail
Additional information about the failure to capture a biometric sample. For more information, see Remarks.
Parameters.EnrollCommit
Contains the results of an asynchronous call to WinBioEnrollCommit.
Parameters.EnrollCommit.Identity
GUID or SID of the template to be saved.
Parameters.EnrollCommit.IsNewTemplate
Specifies whether the template being added to the database is new.
Parameters.EnumEnrollments
Contains the results of an asynchronous call to WinBioEnumEnrollments.
Parameters.EnumEnrollments.Identity
GUID or SID of the template from which the sub-factors were retrieved.
Parameters.EnumEnrollments.SubFactorCount
Number of elements in the array pointed to by the SubFactorArray member.
Parameters.EnumEnrollments.SubFactorArray
Pointer to an array of sub-factors. For more information, see Remarks.
Parameters.CaptureSample
Contains the results of an asynchronous call to WinBioCaptureSample.
Parameters.CaptureSample.Sample
Pointer to a WINBIO_BIR structure that contains the sample.
Parameters.CaptureSample.SampleSize
Size, in bytes, of the WINBIO_BIR structure returned in the Sample member.
Parameters.CaptureSample.RejectDetail
Additional information about the failure to capture a biometric sample. For more information, see Remarks.
Parameters.DeleteTemplate
Contains the results of an asynchronous call to WinBioDeleteTemplate.
Parameters.DeleteTemplate.Identity
GUID or SID of the template that was deleted.
Parameters.DeleteTemplate.SubFactor
Additional information about the template.
Parameters.GetProperty
Contains the results of an asynchronous call to WinBioGetProperty.
Parameters.GetProperty.PropertyType
Source of the property information. Currently this will be WINBIO_PROPERTY_TYPE_UNIT.
Parameters.GetProperty.PropertyId
The property that was queried. Currently this will be WINBIO_PROPERTY_SAMPLE_HINT.
Parameters.GetProperty.Identity
This is a reserved value and will be NULL.
Parameters.GetProperty.SubFactor
This is reserved and will be WINBIO_SUBTYPE_NO_INFORMATION.
Parameters.GetProperty.PropertyBufferSize
Size, in bytes, of the property value pointed to by the PropertyBuffer member.
Parameters.GetProperty.PropertyBuffer
Pointer to the property value.
Parameters.SetProperty
Contains the results of an asynchronous call to WinBioSetProperty. This member is supported starting in Windows 10.
SetProperty.PropretyBufferSize
The size, in bytes, of the structure to which the PropertyBuffer parameter points.
Parameters.SetProperty.PropertyType
A WINBIO_PROPERTY_TYPE value that specifies the type of the property that was set. Currently this can only be WINBIO_PROPERTY_TYPE_ACCOUNT.
Parameters.SetProperty.PropertyId
A WINBIO_PROPERTY_ID value that specifies the property that was set. Currently this value can only be WINBIO_PROPERTY_ANTI_SPOOF_POLICY. All other properties are read-only.
Parameters.SetProperty.Identity
A WINBIO_IDENTITY structure that specifies the account for which the property was set.
Parameters.SetProperty.SubFactor
Reserved. Currently, this value will always be WINBIO_SUBTYPE_NO_INFORMATION.
Parameters.SetProperty.PropertyBufferSize
Parameters.SetProperty.PropertyBuffer
A pointer to a structure that specifies the value to which the property was set. For the WINBIO_PROPERTY_ANTI_SPOOF_POLICY property, the structure is a WINBIO_ANTI_SPOOF_POLICY structure.
Parameters.GetEvent
Contains status information about the event that was raised.
Parameters.GetEvent.Event
Contains event information.
Parameters.ControlUnit
Contains the results of an asynchronous call to WinBioControlUnit or WinBioControlUnitPrivileged.
Parameters.ControlUnit.Component
The component within the biometric unit that performed the operation.
Parameters.ControlUnit.ControlCode
Vendor-defined code recognized by the biometric unit specified by the UnitId parameter of the WinBioControlUnit or WinBioControlUnitPrivileged function and the adapter specified by the Component parameter.
Parameters.ControlUnit.OperationStatus
Vendor-defined status code that specifies the outcome of the control operation.
Parameters.ControlUnit.SendBuffer
Pointer to a buffer that contains the control information sent to the adapter by the component. The format and content of the buffer is vendor-defined.
Parameters.ControlUnit.SendBufferSize
Size, in bytes, of the buffer specified by the SendBuffer member.
Parameters.ControlUnit.ReceiveBuffer
Pointer to a buffer that receives information sent by the adapter specified by the Component member. The format and content of the buffer is vendor-defined.
Parameters.ControlUnit.ReceiveBufferSize
Size, in bytes, of the buffer specified by the ReceiveBuffer member.
Parameters.ControlUnit.ReceiveDataSize
Size, in bytes, of the data written to the buffer specified by the ReceiveBuffer member.
Parameters.EnumServiceProviders
Contains the results of an asynchronous call to WinBioEnumServiceProviders or WinBioAsyncEnumServiceProviders.
Parameters.EnumServiceProviders.BspCount
The number of structures pointed to by the BspSchemaArray member.
Parameters.EnumServiceProviders.BspSchemaArray
Pointer to an array of WINBIO_BSP_SCHEMA structures that contain information about each of the available service providers.
Parameters.EnumBiometricUnits
Contains the results of an asynchronous call to WinBioEnumBiometricUnits or WinBioAsyncEnumBiometricUnits.
Parameters.EnumBiometricUnits.UnitCount
Number of structures pointed to by the UnitSchemaArray member.
Parameters.EnumBiometricUnits.UnitSchemaArray
An array of WINBIO_UNIT_SCHEMA structures that contain information about each enumerated biometric unit.
Parameters.EnumDatabases
Contains the results of an asynchronous call to WinBioEnumDatabases or WinBioAsyncEnumDatabases.
Parameters.EnumDatabases.StorageCount
Number of structures pointed to by the StorageSchemaArray member.
Parameters.EnumDatabases.StorageSchemaArray
Array of WINBIO_STORAGE_SCHEMA structures that contain information about each database.
Parameters.VerifyAndReleaseTicket
Reserved. This member is supported starting in Windows 10.
Parameters.VerifyAndReleaseTicket.Match
Reserved.
Parameters.VerifyAndReleaseTicket.RejectDetail
Reserved.
Parameters.VerifyAndReleaseTicket.Ticket
Reserved.
Parameters.IdentifyAndReleaseTicket
Reserved. This member is supported starting in Windows 10.
Parameters.IdentifyAndReleaseTicket.Identity
Reserved.
Parameters.IdentifyAndReleaseTicket.SubFactor
Reserved.
Parameters.IdentifyAndReleaseTicket.RejectDetail
Reserved.
Parameters.IdentifyAndReleaseTicket.Ticket
Reserved.
Parameters.EnrollSelect
Contains the results of an asynchronous call to WinBioEnrollSelect. This member is supported starting in Windows 10.
Parameters.EnrollSelect.SelectorValue
A value that identifies that individual that was selected for enrollment.
Parameters.MonitorPresence
Contains the results of an asynchronous call to WinBioMonitorPresence. This member is supported starting in Windows 10.
Parameters.MonitorPresence.ChangeType
A WINBIO_PRESENCE_CHANGE value that indicates the type of event that occurred.
Parameters.MonitorPresence.PresenceCount
The size of the array that the MonitorPresence.PresenceArray member points to.
Parameters.MonitorPresence.PresenceArray
Address of the array of WINBIO_PRESENCE structures, one for each individual monitored.
Parameters.GetProtectionPolicy
Parameters.GetProtectionPolicy.Identity
Parameters.GetProtectionPolicy.Policy
Parameters.NotifyUnitStatusChange
Parameters.NotifyUnitStatusChange.ExtendedStatus
Remarks
Asynchronous operations are begun by opening a biometric session or a framework session. Call WinBioAsyncOpenSession to open a biometric session. Call WinBioAsyncOpenFramework to open a framework session.
You can use an asynchronous biometric session handle to call any of the following operations asynchronously:
- WinBioCancel
- WinBioCaptureSample
- WinBioCloseSession
- WinBioControlUnit
- WinBioControlUnitPrivileged
- WinBioDeleteTemplate
- WinBioEnrollBegin
- WinBioEnrollCapture
- WinBioEnrollCommit
- WinBioEnrollDiscard
- WinBioEnumEnrollments
- WinBioGetProperty
- WinBioIdentify
- WinBioLocateSensor
- WinBioLockUnit
- WinBioLogonIdentifiedUser
- WinBioRegisterEventMonitor
- WinBioUnlockUnit
- WinBioUnregisterEventMonitor
- WinBioVerify
- WinBioWait
- WinBioSetProperty
- WinBioEnrollSelect
- WinBioMonitorPresence
You can use an asynchronous framework handle to call the following operations asynchronously:
- WinBioAsyncEnumBiometricUnits
- WinBioAsyncEnumDatabases
- WinBioAsyncOpenFramework
- WinBioAsyncEnumServiceProviders
- WinBioAsyncMonitorFrameworkChanges
The WINBIO_ASYNC_RESULT structure is allocated internally by the Windows Biometric Framework. Therefore, when you are through using it, call WinBioFree to release the allocated memory and avoid leaks. Because this also releases all nested data structures, you should not keep a copy of any pointers returned in the WINBIO_ASYNC_RESULT structure. If you want to save any data returned in a nested structure, make a private copy of that data before calling WinBioFree.
Windows 8, Windows Server 2012, Windows 8.1 and Windows Server 2012 R2: The Windows Biometric Framework supports only fingerprint readers. Therefore, if an operation fails and returns additional information in a WINBIO_REJECT_DETAIL constant, it will be one of the following values:
- WINBIO_FP_TOO_HIGH
- WINBIO_FP_TOO_LOW
- WINBIO_FP_TOO_LEFT
- WINBIO_FP_TOO_RIGHT
- WINBIO_FP_TOO_FAST
- WINBIO_FP_TOO_SLOW
- WINBIO_FP_POOR_QUALITY
- WINBIO_FP_TOO_SKEWED
- WINBIO_FP_TOO_SHORT
- WINBIO_FP_MERGE_FAILURE
Further, if an operation uses a WINBIO_BIOMETRIC_SUBTYPE data type, it will be one of the following values:
- WINBIO_ANSI_381_POS_UNKNOWN
- WINBIO_ANSI_381_POS_RH_THUMB
- WINBIO_ANSI_381_POS_RH_INDEX_FINGER
- WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER
- WINBIO_ANSI_381_POS_RH_RING_FINGER
- WINBIO_ANSI_381_POS_RH_LITTLE_FINGER
- WINBIO_ANSI_381_POS_LH_THUMB
- WINBIO_ANSI_381_POS_LH_INDEX_FINGER
- WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER
- WINBIO_ANSI_381_POS_LH_RING_FINGER
- WINBIO_ANSI_381_POS_LH_LITTLE_FINGER
- WINBIO_ANSI_381_POS_RH_FOUR_FINGERS
- WINBIO_ANSI_381_POS_LH_FOUR_FINGERS
- WINBIO_ANSI_381_POS_TWO_THUMBS
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows 8 [desktop apps only] |
Minimum supported server | Windows Server 2012 [desktop apps only] |
Header | winbio.h |