WinBioAsyncOpenSession 函数 (winbio.h)

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

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

语法

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 值，该值指定将在会话中使用的生物识别单元的类型。 这可以是以下值之一：

值	含义
WINBIO_POOL_SYSTEM	会话连接到由服务提供商管理的生物识别单元的共享集合。
WINBIO_POOL_PRIVATE	会话连接到由调用方管理的生物识别单元集合。

[in] Flags

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

值	含义
WINBIO_FLAG_DEFAULT	组：配置 生物识别单元按安装期间指定的方式运行。 当 poolType 参数 WINBIO_POOL_SYSTEM时，必须使用此值。
WINBIO_FLAG_BASIC	组：配置 生物识别单元仅作为基本捕获设备运行。 所有处理、匹配和存储操作都由软件插件执行。
WINBIO_FLAG_ADVANCED	组：配置 生物识别单元使用内部处理和存储功能。
WINBIO_FLAG_RAW	组：访问 客户端应用程序使用 WinBioCaptureSample 捕获原始生物识别数据。
WINBIO_FLAG_MAINTENANCE	组：访问 客户端通过调用 WinBioControlUnitPrivileged 对生物识别单元执行供应商定义的控制操作。

[in, optional] UnitArray

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

[in, optional] UnitCount

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

[in, optional] DatabaseId

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

值	含义
WINBIO_DB_DEFAULT	传感器池中的每个生物识别单元都使用默认生物识别单元配置中指定的默认数据库。 如果WINBIO_POOL_SYSTEM PoolType 参数，则必须指定此值。 如果 PoolType 参数WINBIO_POOL_PRIVATE，则不能使用此值
WINBIO_DB_BOOTSTRAP	可以指定此值用于启动 Windows 之前的方案。 通常，数据库是传感器芯片的一部分或 BIOS 的一部分，只能用于模板注册和删除。
WINBIO_DB_ONCHIP	数据库位于传感器芯片上，可用于注册和匹配。

[in] NotificationMethod

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

值	含义
WINBIO_ASYNC_NOTIFY_CALLBACK	会话调用应用程序定义的回调函数。
WINBIO_ASYNC_NOTIFY_MESSAGE	会话将窗口消息发布到应用程序的消息队列。

[in, optional] TargetWindow

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

[in, optional] MessageCode

框架必须发送的窗口消息代码来表示完成通知。 除非 NotificationMethod 参数设置为 WINBIO_ASYNC_NOTIFY_MESSAGE，否则将忽略此值。 该值必须位于要0xBFFF WM_APP (0x8000) 范围内。

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 值。

返回代码	说明
E_OUTOFMEMORY	没有足够的内存可用于创建生物识别会话。
E_INVALIDARG	如果将通知方法设置为 WINBIO_ASYNC_NOTIFY_MESSAGE， 则 TargetWindow 参数不能为 NULL 或 HWND_BROADCASTMessageCode 参数不能为零 (0) 。
E_POINTER	必须设置 SessionHandle 参数和 AsynchronousOpen 参数。 如果将 notification 方法设置为 WINBIO_ASYNC_NOTIFY_CALLBACK，则还必须在 CallbackRoutine 参数中指定回调函数的地址。
E_ACCESSDENIED	Flags 参数包含WINBIO_FLAG_RAW或WINBIO_FLAG_MAINTENANCE标志，并且调用方尚未被授予任何访问权限。
WINBIO_E_INVALID_UNIT	UnitArray 参数中指定的一个或多个生物识别单位号无效。
WINBIO_E_NOT_ACTIVE_CONSOLE	客户端应用程序正在远程桌面客户端上运行，并尝试打开系统池会话。
WINBIO_E_SENSOR_UNAVAILABLE	PoolType 参数设置为WINBIO_POOL_PRIVATE并且该池中请求的一个或多个传感器不可用。
WINBIO_E_DISABLED	当前管理策略禁止使用 Windows 生物识别框架 API。

注解

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

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

WinBioAsyncOpenSession 返回的会话句柄不能与以下函数一起使用：

• WinBioCaptureSampleWithCallback
• WinBioEnrollCaptureWithCallback
• WinBioIdentifyWithCallback
• WinBioIdentifyWithCallback

这些函数最初在 Windows 7 中可用，具有不兼容的回调签名，不建议在新应用程序中使用它们。 需要异步回调的开发人员应改为使用 WinBioAsyncOpenSession 和 NotificationMethodWINBIO_ASYNC_NOTIFY_CALLBACK。

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

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

要求

最低受支持的客户端	Windows 8 [仅限桌面应用]
最低受支持的服务器	Windows Server 2012 [仅限桌面应用]
目标平台	Windows
标头	winbio.h (包括 Winbio.h)
Library	Winbio.lib
DLL	Winbio.dll

另请参阅

WinBioAsyncOpenFramework

WinBioCloseSession

WinBioOpenSession