WinBioControlUnit 函数 (winbio.h)

  • 项目

允许调用方在生物识别单元上执行供应商定义的控制操作。 从Windows 10版本 1607 开始，此函数可用于移动映像。 此函数用于访问不需要提升特权的扩展供应商操作。 如果需要访问权限，请调用 WinBioControlUnitPrivileged 函数。

语法

HRESULT WinBioControlUnit(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [in]            WINBIO_UNIT_ID        UnitId,
  [in]            WINBIO_COMPONENT      Component,
  [in]            ULONG                 ControlCode,
                  PUCHAR                SendBuffer,
  [in]            SIZE_T                SendBufferSize,
                  PUCHAR                ReceiveBuffer,
  [in]            SIZE_T                ReceiveBufferSize,
                  SIZE_T                *ReceiveDataSize,
  [out, optional] ULONG                 *OperationStatus
);

参数

[in] SessionHandle

标识打开的生物识别会话 的WINBIO_SESSION_HANDLE 值。 通过调用 WinBioOpenSession 打开同步会话句柄。 通过调用 WinBioAsyncOpenSession 打开异步会话句柄。

[in] UnitId

标识生物识别单元 的WINBIO_UNIT_ID 值。 此值必须与之前在 WinBioLockUnit 函数中使用的单位 ID 相对应。

[in] Component

一个WINBIO_COMPONENT值，该值指定生物识别单元中应执行操作的组件。 这可以是以下值之一。

值 含义
WINBIO_COMPONENT_SENSOR
 将命令发送到传感器适配器。
WINBIO_COMPONENT_ENGINE
 将命令发送到引擎适配器。
WINBIO_COMPONENT_STORAGE
 将命令发送到存储适配器。

[in] ControlCode

由 UnitId 参数指定的生物识别单元和 Component 参数指定的适配器识别的供应商定义代码。

SendBuffer

包含要发送到 Component 参数指定的适配器的控件信息的缓冲区的地址。 缓冲区的格式和内容由供应商定义。

[in] SendBufferSize

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

ReceiveBuffer

接收由 Component 参数指定的适配器发送的信息的缓冲区的地址。 缓冲区的格式和内容由供应商定义。

[in] ReceiveBufferSize

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

ReceiveDataSize

指向 SIZE_T 值的指针，该值包含写入 ReceiveBuffer 参数指定的缓冲区的数据的大小（以字节为单位）。

[out, optional] OperationStatus

指向包含供应商定义状态代码的整数的指针，该代码指定控制操作的结果。

返回值

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

返回代码 说明
E_HANDLE
 会话句柄无效。
E_INVALIDARG
 无法识别 ControlCode 参数中指定的值。
E_POINTER
 SendBuffer、ReceiveBuffer、ReceiveDataSize、OperationStatus 参数不能为 NULL。
WINBIO_E_INVALID_CONTROL_CODE
 无法识别 ControlCode 参数中指定的值。
WINBIO_E_LOCK_VIOLATION
 必须先锁定 UnitId 参数指定的生物识别单元，然后才能执行任何控制操作。

注解

在调用 WinBioControlUnit 之前，必须调用 WinBioLockUnit。 WinBioLockUnit 函数创建一个锁定区域，可在其中安全地执行供应商定义的操作。

创建插件的供应商必须决定哪些扩展操作具有特权，哪些操作可供所有客户端使用。 若要执行特权操作，客户端应用程序必须调用 WinBioControlUnitPrivileged 函数。 Windows 生物识别框架仅允许具有相应访问权限的客户端调用 WinBioControlUnitPrivileged。

若要同步使用 WinBioControlUnit ，请使用通过调用 WinBioOpenSession 创建的会话句柄调用函数。 函数将一直阻止，直到操作完成或遇到错误。

若要异步使用 WinBioControlUnit ，请使用通过调用 WinBioAsyncOpenSession 创建的会话句柄调用函数。 框架分配 WINBIO_ASYNC_RESULT 结构，并使用它返回有关操作成功或失败的信息。 WINBIO_ASYNC_RESULT结构将返回到应用程序回调或应用程序消息队列，具体取决于在 WinBioAsyncOpenSession 函数的 NotificationMethod 参数中设置的值。

  • 如果选择使用回调接收完成通知，则必须实现 PWINBIO_ASYNC_COMPLETION_CALLBACK 函数并将 NotificationMethod 参数设置为 WINBIO_ASYNC_NOTIFY_CALLBACK。
  • 如果选择使用应用程序消息队列接收完成通知，则必须将 NotificationMethod 参数设置为 WINBIO_ASYNC_NOTIFY_MESSAGE。 框架返回指向窗口消息的 LPARAM 字段的WINBIO_ASYNC_RESULT指针。
若要防止内存泄漏，必须在使用完WINBIO_ASYNC_RESULT结构后调用 WinBioFree 以释放它。

要求

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

另请参阅

WinBioControlUnitPrivileged

WinBioLockUnit