Skip to main content
WINBIO_ASYNC_RESULT structure

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 {
      ULONG None;
    } 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;
  } 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

Biometric unit ID number.

UserData

Address of a 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.

Verify

Contains the results of an asynchronous call to WinBioVerify.

Match

Specifies whether the captured sample matched the user identity.

RejectDetail

Additional information about verification failure. For more information, see Remarks.

Identify

Contains the results of an asynchronous call to WinBioIdentify.

Identity

GUID or SID of the user providing the biometric sample.

SubFactor

Sub-factor associated with the biometric sample. For more information, see Remarks.

RejectDetail

Additional information about the failure, if any, to capture and identify a biometric sample. For more information, see Remarks.

EnrollBegin

Contains the results of an asynchronous call to WinBioEnrollBegin.

SubFactor

Additional information about the enrollment. For more information, see Remarks.

EnrollCapture

Contains the results of an asynchronous call to WinBioEnrollCapture.

RejectDetail

Additional information about the failure to capture a biometric sample. For more information, see Remarks.

EnrollCommit

Contains the results of an asynchronous call to WinBioEnrollCommit.

Identity

GUID or SID of the template to be saved.

IsNewTemplate

Specifies whether the template being added to the database is new.

EnumEnrollments

Contains the results of an asynchronous call to WinBioEnumEnrollments.

Identity

GUID or SID of the template from which the sub-factors were retrieved.

SubFactorCount

Number of elements in the array pointed to by the SubFactorArray member.

SubFactorArray

Pointer to an array of sub-factors. For more information, see Remarks.

CaptureSample

Contains the results of an asynchronous call to WinBioCaptureSample.

Sample

Pointer to a WINBIO_BIR structure that contains the sample.

SampleSize

Size, in bytes, of the WINBIO_BIR structure returned in the Sample member.

RejectDetail

Additional information about the failure to capture a biometric sample. For more information, see Remarks.

DeleteTemplate

Contains the results of an asynchronous call to WinBioDeleteTemplate.

Identity

GUID or SID of the template that was deleted.

SubFactor

Additional information about the template.

GetProperty

Contains the results of an asynchronous call to WinBioGetProperty.

PropertyType

Source of the property information. Currently this will be WINBIO_PROPERTY_TYPE_UNIT.

PropertyId

The property that was queried. Currently this will be WINBIO_PROPERTY_SAMPLE_HINT.

Identity

This is a reserved value and will be NULL.

SubFactor

This is reserved and will be WINBIO_SUBTYPE_NO_INFORMATION.

PropertyBufferSize

Size, in bytes, of the property value pointed to by the PropertyBuffer member.

PropertyBuffer

Pointer to the property value.

SetProperty

Reserved.

None

Reserved.

GetEvent

Contains status information about the event that was raised.

Event

Contains event information.

ControlUnit

Contains the results of an asynchronous call to WinBioControlUnit or WinBioControlUnitPrivileged.

Component

The component within the biometric unit that performed the operation.

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.

OperationStatus

Vendor-defined status code that specifies the outcome of the control operation.

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.

SendBufferSize

Size, in bytes, of the buffer specified by the SendBuffer member.

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.

ReceiveBufferSize

Size, in bytes, of the buffer specified by the ReceiveBuffer member.

ReceiveDataSize

Size, in bytes, of the data written to the buffer specified by the ReceiveBuffer member.

EnumServiceProviders

Contains the results of an asynchronous call to WinBioEnumServiceProviders or WinBioAsyncEnumServiceProviders.

BspCount

The number of structures pointed to by the BspSchemaArray member.

BspSchemaArray

Pointer to an array of WINBIO_BSP_SCHEMA structures that contain information about each of the available service providers.

EnumBiometricUnits

Contains the results of an asynchronous call to WinBioEnumBiometricUnits or WinBioAsyncEnumBiometricUnits.

UnitCount

Number of structures pointed to by the UnitSchemaArray member.

UnitSchemaArray

An array of WINBIO_UNIT_SCHEMA structures that contain information about each enumerated biometric unit.

EnumDatabases

Contains the results of an asynchronous call to WinBioEnumDatabases or WinBioAsyncEnumDatabases.

StorageCount

Number of structures pointed to by the StorageSchemaArray member.

StorageSchemaArray

Array of WINBIO_STORAGE_SCHEMA structures that contain information about each database.

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:

You can use an asynchronous framework handle to call the following operations asynchronously:

Currently, 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 datatype, 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

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.

Requirements

Minimum supported client

Windows 8 [desktop apps only]

Minimum supported server

Windows Server 2012 [desktop apps only]

Header

Winbio.h

See also

WinBioAsyncOpenSession
WinBioAsyncOpenFramework
WINBIO_REJECT_DETAIL Constants