WinBioAsyncOpenSession 函数 （winbio.h）

异步连接到生物识别服务提供商和一个或多个生物识别单元。 从 Windows 10 版本 1607 开始，此函数可用于移动映像。 如果成功，该函数将返回生物识别会话句柄。 使用此句柄执行的每个作都将异步完成，包括 WinBioCloseSession，结果将使用 NotificationMethod 参数中指定的方法返回到客户端应用程序。

有关此函数的同步版本，请参阅 WinBioOpenSession。

Syntax

HRESULT WinBioAsyncOpenSession(
  [in]            WINBIO_BIOMETRIC_TYPE             Factor,
  [in]            WINBIO_POOL_TYPE                  PoolType,
  [in]            WINBIO_SESSION_FLAGS              Flags,
  [in, optional]  WINBIO_UNIT_ID                    *UnitArray,
  [in, optional]  SIZE_T                            UnitCount,
  [in, optional]  GUID                              *DatabaseId,
  [in]            WINBIO_ASYNC_NOTIFICATION_METHOD  NotificationMethod,
  [in, optional]  HWND                              TargetWindow,
  [in, optional]  UINT                              MessageCode,
  [in, optional]  PWINBIO_ASYNC_COMPLETION_CALLBACK CallbackRoutine,
  [in, optional]  PVOID                             UserData,
  [in]            BOOL                              AsynchronousOpen,
  [out, optional] WINBIO_SESSION_HANDLE             *SessionHandle
);

参数

[in] Factor

指定要枚举的生物识别单元类型的 WINBIO_BIOMETRIC_TYPE 标志的位掩码。 目前仅支持 WINBIO_TYPE_FINGERPRINT 。

[in] PoolType

一个 ULONG 值，该值指定将在会话中使用的生物识别单元的类型。 这可以是以下值之一：

[in] Flags

一个 ULONG 值，该值指定新会话的生物识别单元配置和访问特征。 配置标志指定会话中单元的常规配置。 访问标志指定应用程序如何使用生物识别单元。 必须指定一个配置标志，但可以将该标志与任何访问标志合并。

[in, optional] UnitArray

指向要包含在会话中的生物识别单元标识符数组的指针。 可以调用 WinBioEnumBiometricUnits 来枚举生物识别单元。 如果 PoolType 参数WINBIO_POOL_SYSTEM，请将此值设置为 NULL。

[in, optional] UnitCount

一个值，该值指定 UnitArray 参数指向的数组中的元素数。 如果 PoolType 参数 WINBIO_POOL_SYSTEM，请将此值设置为零。

[in, optional] DatabaseId

一个值，该值指定会话要使用的数据库。 如果 PoolType 参数 WINBIO_POOL_PRIVATE，则必须指定已安装数据库的 GUID。 如果未WINBIO_POOL_PRIVATEPoolType 参数，则可以指定以下常见值之一。

[in] NotificationMethod

指定如何将此生物识别会话中异步作的完成通知传送到客户端应用程序。 这必须是以下值之一。

[in, optional] TargetWindow

将接收完成通知的窗口的句柄。 除非 NotificationMethod 参数设置为 WINBIO_ASYNC_NOTIFY_MESSAGE，否则将忽略此值。

[in, optional] MessageCode

框架必须发送的窗口消息代码以表示完成通知。 除非 NotificationMethod 参数设置为 WINBIO_ASYNC_NOTIFY_MESSAGE，否则将忽略此值。 该值必须在WM_APP（0x8000）范围内才能0xBFFF。

Windows 生物识别框架将消息的 LPARAM 值设置为包含作结果 的WINBIO_ASYNC_RESULT 结构地址。 使用完结构后，必须调用 WinBioFree 释放结构。

[in, optional] CallbackRoutine

使用会话句柄启动作时要调用的回调例程的地址。 除非 NotificationMethod 参数设置为 WINBIO_ASYNC_NOTIFY_CALLBACK，否则将忽略此值。

[in, optional] UserData

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

[in] AsynchronousOpen

指定是否在打开框架会话之前阻止。 指定 FALSE 会导致进程阻止。 指定 TRUE 会导致会话以异步方式打开。

如果指定 FALSE 以同步打开框架会话，则 HRESULT 返回值中的此函数将成功或失败直接返回到调用方。 如果会话成功打开，则应用程序收到的第一个异步完成事件将用于在框架打开后请求的异步作。

如果指定 TRUE 以异步方式打开框架会话，则收到的第一个异步完成通知将用于打开框架。 如果 NotificationMethod 参数设置为WINBIO_ASYNC_NOTIFY_CALLBACK，作结果将传递到 CallbackRoutine 参数指定的回调函数中的WINBIO_ASYNC_RESULT结构。 如果将 NotificationMethod 参数设置为 WINBIO_ASYNC_NOTIFY_MESSAGE，作结果将传递到窗口消息的 LPARAM 字段指向 的WINBIO_ASYNC_RESULT 结构。

[out, optional] SessionHandle

如果函数不成功，此参数将为 NULL。

如果会话以同步方式成功打开，此参数将包含指向会话句柄的指针。

如果指定以异步方式打开会话，此方法将立即返回，会话句柄将为 NULL，并且必须检查 WINBIO_ASYNC_RESULT 结构以确定会话是否已成功打开。

返回值

如果函数成功，它将返回 S_OK。 如果函数失败，它将返回指示错误的 HRESULT 值。 可能的值包括但不限于下表中的值。 有关常见错误代码的列表，请参阅 通用 HRESULT 值。

注解

WinBioAsyncOpenSession 函数返回的会话句柄可用于为以下任一函数生成异步完成通知：

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

• WinBioCaptureSampleWithCallback
• WinBioEnrollCaptureWithCallback
• WinBioIdentifyWithCallback
• WinBioIdentifyWithCallback

SyncOpen 参数仅确定打开的作是否会阻止。 此参数不会影响使用会话句柄的后续调用的完成行为。

如果将 SyncOpen 参数设置为 TRUE，此函数将在执行参数的初始验证后立即返回 S_OK 。 检测到的任何超出该点的错误都将使用 NotificationMethod 参数指定的方法报告给调用方。 也就是说，成功的返回值仅指示 WinBioAsyncOpenSession 参数正常，而不是打开作成功。 若要确定打开的作是否成功，必须检查 WINBIO_ASYNC_RESULT 结构。

要求

另请参阅

WinBioAsyncOpenFramework

WinBioCloseSession

WinBioOpenSession