WINBIO_ASYNC_RESULT结构 (winbio.h)

WINBIO_ASYNC_RESULT 结构包含异步操作的结果。

语法

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;

成员

SessionHandle

通过调用 WinBioAsyncOpenSession 函数或 WinBioAsyncOpenFramework 函数启动的异步会话的句柄。

Operation

异步操作的类型。 有关详细信息，请参阅 WINBIO_OPERATION_TYPE常量。

SequenceNumber

异步操作的序列号。 为生物识别会话中的每个操作按顺序分配整数，从一 (1) 开始。 对于任何会话，始终为打开操作分配第一个序列号，为关闭操作分配最后一个序列号。 如果应用程序将多个操作排队，则可以使用序列号来执行错误处理。 例如，可以在将特定序列号发送到应用程序之前忽略操作结果。

TimeStamp

生物识别操作开始的系统日期和时间。 有关详细信息，请参阅 GetSystemTimeAsFileTime 函数。

ApiStatus

操作返回的错误代码。

UnitId

执行操作的生物识别单元的数字单位标识符。

UserData

调用方提供的可选缓冲区的地址。 框架或生物识别单元不会修改缓冲区。 应用程序可以使用数据来帮助它确定在收到完成通知后要执行的操作，或维护有关所请求操作的其他信息。

Parameters

包含嵌套结构的联合，这些结构包含有关客户端应用程序启动的异步操作成功或失败的其他信息。

Parameters.Verify

包含对 WinBioVerify 的异步调用的结果。

Parameters.Verify.Match

指定捕获的示例是否与用户标识匹配。

Parameters.Verify.RejectDetail

有关验证失败的其他信息。 有关详细信息，请参阅“备注”。

Parameters.Identify

包含对 WinBioIdentify 的异步调用的结果。

Parameters.Identify.Identity

提供生物识别示例的用户的 GUID 或 SID。

Parameters.Identify.SubFactor

与生物识别样本关联的子因素。 有关详细信息，请参阅“备注”。

Parameters.Identify.RejectDetail

有关捕获和识别生物识别样本的失败（如果有）的其他信息。 有关详细信息，请参阅“备注”。

Parameters.EnrollBegin

包含对 WinBioEnrollBegin 的异步调用的结果。

Parameters.EnrollBegin.SubFactor

有关注册的其他信息。 有关详细信息，请参阅“备注”。

Parameters.EnrollCapture

包含对 WinBioEnrollCapture 的异步调用的结果。

Parameters.EnrollCapture.RejectDetail

有关无法捕获生物识别示例的其他信息。 有关详细信息，请参阅“备注”。

Parameters.EnrollCommit

包含对 WinBioEnrollCommit 的异步调用的结果。

Parameters.EnrollCommit.Identity

要保存的模板的 GUID 或 SID。

Parameters.EnrollCommit.IsNewTemplate

指定要添加到数据库的模板是否为新模板。

Parameters.EnumEnrollments

包含对 WinBioEnumEnrollments 的异步调用的结果。

Parameters.EnumEnrollments.Identity

从中检索子因素的模板的 GUID 或 SID。

Parameters.EnumEnrollments.SubFactorCount

SubFactorArray 成员指向的数组中的元素数。

Parameters.EnumEnrollments.SubFactorArray

指向子因素数组的指针。 有关详细信息，请参阅“备注”。

Parameters.CaptureSample

包含对 WinBioCaptureSample 的异步调用的结果。

Parameters.CaptureSample.Sample

指向包含示例 的WINBIO_BIR 结构的指针。

Parameters.CaptureSample.SampleSize

Sample 成员中返回的WINBIO_BIR结构的大小（以字节为单位）。

Parameters.CaptureSample.RejectDetail

有关无法捕获生物识别示例的其他信息。 有关详细信息，请参阅“备注”。

Parameters.DeleteTemplate

包含对 WinBioDeleteTemplate 的异步调用的结果。

Parameters.DeleteTemplate.Identity

已删除的模板的 GUID 或 SID。

Parameters.DeleteTemplate.SubFactor

有关模板的其他信息。

Parameters.GetProperty

包含对 WinBioGetProperty 的异步调用的结果。

Parameters.GetProperty.PropertyType

属性信息的源。 目前，这将 WINBIO_PROPERTY_TYPE_UNIT。

Parameters.GetProperty.PropertyId

查询的属性。 目前，这将 WINBIO_PROPERTY_SAMPLE_HINT。

Parameters.GetProperty.Identity

这是一个保留值，将为 NULL。

Parameters.GetProperty.SubFactor

这是保留的，将 WINBIO_SUBTYPE_NO_INFORMATION。

Parameters.GetProperty.PropertyBufferSize

PropertyBuffer 成员指向的属性值的大小（以字节为单位）。

Parameters.GetProperty.PropertyBuffer

指向属性值的指针。

Parameters.SetProperty

包含对 WinBioSetProperty 的异步调用的结果。 从 Windows 10 开始支持此成员。

SetProperty.PropretyBufferSize

PropertyBuffer 参数指向的结构的大小（以字节为单位）。

Parameters.SetProperty.PropertyType

一个WINBIO_PROPERTY_TYPE值，该值指定所设置的属性的类型。 目前只能 WINBIO_PROPERTY_TYPE_ACCOUNT。

Parameters.SetProperty.PropertyId

一个WINBIO_PROPERTY_ID值，该值指定已设置的属性。 目前，此值只能 WINBIO_PROPERTY_ANTI_SPOOF_POLICY。 所有其他属性都是只读的。

Parameters.SetProperty.Identity

一个WINBIO_IDENTITY结构，用于指定为其设置了属性的帐户。

Parameters.SetProperty.SubFactor

保留。 目前，此值将始终 WINBIO_SUBTYPE_NO_INFORMATION。

Parameters.SetProperty.PropertyBufferSize

Parameters.SetProperty.PropertyBuffer

指向结构的指针，该结构指定属性所要设置的值。 对于 WINBIO_PROPERTY_ANTI_SPOOF_POLICY 属性，结构是 WINBIO_ANTI_SPOOF_POLICY 结构。

Parameters.GetEvent

包含有关引发的事件的状态信息。

Parameters.GetEvent.Event

包含事件信息。

Parameters.ControlUnit

包含对 WinBioControlUnit 或 WinBioControlUnitPrivileged 的异步调用的结果。

Parameters.ControlUnit.Component

执行操作的生物识别单元中的组件。

Parameters.ControlUnit.ControlCode

供应商定义的代码由 WinBioControlUnit 或 WinBioControlUnitPrivileged 函数的 UnitId 参数指定的生物识别单元以及 Component 参数指定的适配器所识别。

Parameters.ControlUnit.OperationStatus

供应商定义的状态代码，指定控制操作的结果。

Parameters.ControlUnit.SendBuffer

指向缓冲区的指针，该缓冲区包含组件发送到适配器的控件信息。 缓冲区的格式和内容由供应商定义。

Parameters.ControlUnit.SendBufferSize

SendBuffer 成员指定的缓冲区的大小（以字节为单位）。

Parameters.ControlUnit.ReceiveBuffer

指向缓冲区的指针，该缓冲区接收由 Component 成员指定的适配器发送的信息。 缓冲区的格式和内容由供应商定义。

Parameters.ControlUnit.ReceiveBufferSize

ReceiveBuffer 成员指定的缓冲区的大小（以字节为单位）。

Parameters.ControlUnit.ReceiveDataSize

写入 由 ReceiveBuffer 成员指定的缓冲区的数据的大小（以字节为单位）。

Parameters.EnumServiceProviders

包含对 WinBioEnumServiceProviders 或 WinBioAsyncEnumServiceProviders 的异步调用的结果。

Parameters.EnumServiceProviders.BspCount

BspSchemaArray 成员指向的结构数。

Parameters.EnumServiceProviders.BspSchemaArray

指向包含每个可用服务提供程序相关信息的 WINBIO_BSP_SCHEMA 结构的数组的指针。

Parameters.EnumBiometricUnits

包含对 WinBioEnumBiometricUnits 或 WinBioAsyncEnumBiometricUnits 的异步调用的结果。

Parameters.EnumBiometricUnits.UnitCount

UnitSchemaArray 成员指向的结构数。

Parameters.EnumBiometricUnits.UnitSchemaArray

包含每个枚举生物识别单元相关信息 的WINBIO_UNIT_SCHEMA 结构的数组。

Parameters.EnumDatabases

包含对 WinBioEnumDatabases 或 WinBioAsyncEnumDatabases 的异步调用的结果。

Parameters.EnumDatabases.StorageCount

StorageSchemaArray 成员指向的结构数。

Parameters.EnumDatabases.StorageSchemaArray

包含每个数据库相关信息 的WINBIO_STORAGE_SCHEMA 结构的数组。

Parameters.VerifyAndReleaseTicket

保留。 从 Windows 10 开始支持此成员。

Parameters.VerifyAndReleaseTicket.Match

保留。

Parameters.VerifyAndReleaseTicket.RejectDetail

保留。

Parameters.VerifyAndReleaseTicket.Ticket

保留。

Parameters.IdentifyAndReleaseTicket

保留。 从 Windows 10 开始支持此成员。

Parameters.IdentifyAndReleaseTicket.Identity

保留。

Parameters.IdentifyAndReleaseTicket.SubFactor

保留。

Parameters.IdentifyAndReleaseTicket.RejectDetail

保留。

Parameters.IdentifyAndReleaseTicket.Ticket

保留。

Parameters.EnrollSelect

包含对 WinBioEnrollSelect 的异步调用的结果。 从 Windows 10 开始支持此成员。

Parameters.EnrollSelect.SelectorValue

一个 值，该值标识为注册选择的个人。

Parameters.MonitorPresence

包含对 WinBioMonitorPresence 的异步调用的结果。 从 Windows 10 开始支持此成员。

Parameters.MonitorPresence.ChangeType

指示所发生事件的类型的 WINBIO_PRESENCE_CHANGE 值。

Parameters.MonitorPresence.PresenceCount

MonitorPresence.PresenceArray 成员指向的数组的大小。

Parameters.MonitorPresence.PresenceArray

WINBIO_PRESENCE结构数组的地址，每个受监视者对应一个。

Parameters.GetProtectionPolicy

Parameters.GetProtectionPolicy.Identity

Parameters.GetProtectionPolicy.Policy

Parameters.NotifyUnitStatusChange

Parameters.NotifyUnitStatusChange.ExtendedStatus

注解

异步操作通过打开生物识别会话或框架会话开始。 调用 WinBioAsyncOpenSession 以打开生物识别会话。 调用 WinBioAsyncOpenFramework 以打开框架会话。

可以使用异步生物识别会话句柄以异步方式调用以下任何操作：

• WinBioCancel
• WinBioCaptureSample
• WinBioCloseSession
• WinBioControlUnit
• WinBioControlUnitPrivileged
• WinBioDeleteTemplate
• WinBioEnrollBegin
• WinBioEnrollCapture
• WinBioEnrollCommit
• WinBioEnrollDiscard
• WinBioEnumEnrollments
• WinBioGetProperty
• WinBioIdentify
• WinBioLocateSensor
• WinBioLockUnit
• WinBioLogonIdentifiedUser
• WinBioRegisterEventMonitor
• WinBioUnlockUnit
• WinBioUnregisterEventMonitor
• WinBioVerify
• WinBioWait
• WinBioSetProperty
• WinBioEnrollSelect
• WinBioMonitorPresence

可以使用异步框架句柄以异步方式调用以下操作：

• WinBioAsyncEnumBiometricUnits
• WinBioAsyncEnumDatabases
• WinBioAsyncOpenFramework
• WinBioAsyncEnumServiceProviders
• WinBioAsyncMonitorFrameworkChanges

WINBIO_ASYNC_RESULT结构由 Windows 生物识别框架在内部分配。 因此，使用时，请调用 WinBioFree 释放分配的内存并避免泄漏。 因为这也会释放所有嵌套数据结构，因此不应保留 WINBIO_ASYNC_RESULT 结构中返回的任何指针的副本。 如果要保存嵌套结构中返回的任何数据，请在调用 WinBioFree 之前创建该数据的专用副本。

Windows 8、Windows Server 2012、Windows 8.1 和 Windows Server 2012 R2：Windows 生物识别框架仅支持指纹读取器。 因此，如果操作失败并在 WINBIO_REJECT_DETAIL 常量中返回其他信息，则它将是以下值之一：

• 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

此外，如果操作使用 WINBIO_BIOMETRIC_SUBTYPE 数据类型，它将是以下值之一：

• 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

要求

要求	值
最低受支持的客户端	Windows 8 [仅限桌面应用]
最低受支持的服务器	Windows Server 2012 [仅限桌面应用]
标头	winbio.h

另请参阅

WINBIO_REJECT_DETAIL常量

WinBioAsyncOpenFramework

WinBioAsyncOpenSession