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

See also

WINBIO_REJECT_DETAIL Constants

WinBioAsyncOpenFramework

WinBioAsyncOpenSession