WinBioControlUnitPrivileged 函数 (winbio.h)

  • 项目

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

语法

HRESULT WinBioControlUnitPrivileged(
  [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。
E_ACCESSDENIED
 调用方没有执行操作的权限，或者未使用 WINBIO_FLAG_MAINTENANCE 打开会话。
E_INVALIDARG
 无法识别 ControlCode 参数中指定的值。
WINBIO_E_LOCK_VIOLATION
 必须先锁定 UnitId 参数指定的生物识别单元，然后才能执行任何控制操作。

注解

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

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

若要成功调用此函数，必须通过指定 WINBIO_FLAG_MAINTENANCE打开会话句柄。 只有管理员和本地系统帐户具有必要的权限。

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

若要异步使用 WinBioControlUnitPrivileged ，请使用通过调用 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

另请参阅

WinBioControlUnit

WinBioLockUnit