WinBioGetProperty 函数 (winbio.h)

  • 项目

检索会话、单元或模板属性。 从Windows 10版本 1607 开始，此函数可用于移动映像。

语法

HRESULT WinBioGetProperty(
  [in]            WINBIO_SESSION_HANDLE    SessionHandle,
  [in]            WINBIO_PROPERTY_TYPE     PropertyType,
  [in]            WINBIO_PROPERTY_ID       PropertyId,
  [in, optional]  WINBIO_UNIT_ID           UnitId,
  [in, optional]  WINBIO_IDENTITY          *Identity,
  [in, optional]  WINBIO_BIOMETRIC_SUBTYPE SubFactor,
                  PVOID                    *PropertyBuffer,
  [out, optional] SIZE_T                   *PropertyBufferSize
);

参数

[in] SessionHandle

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

[in] PropertyType

一个WINBIO_PROPERTY_TYPE值，该值指定属性信息的源。 目前必须 WINBIO_PROPERTY_TYPE_UNIT 或 WINBIO_PROPERTY_TYPE_ACCOUNT。 有关属性类型的详细信息，请参阅 WINBIO_PROPERTY_TYPE常量。

从 Windows 10 开始支持WINBIO_PROPERTY_TYPE_ACCOUNT值。

[in] PropertyId

一个WINBIO_PROPERTY_ID值，该值指定要查询的属性。 可以使用以下值。

值 含义
WINBIO_PROPERTY_SAMPLE_HINT
 估计完成注册模板所需的最佳生物识别样本的最大数量。 属性查询的结果在 PropertyBuffer 参数指向的缓冲区中作为包含提示的 ULONG 值返回。
WINBIO_PROPERTY_EXTENDED_SENSOR_INFO
包含有关连接到特定生物识别单元的传感器组件的功能和属性的扩展信息。 属性查询的结果在 PropertyBuffer 参数作为 WINBIO_EXTENDED_SENSOR_INFO 结构指向的缓冲区中返回。 从 Windows 10 开始支持此值。
WINBIO_PROPERTY_EXTENDED_ENGINE_INFO
包含有关连接到特定生物识别单元的引擎组件的功能和属性的扩展信息。 属性查询的结果在 PropertyBuffer 参数作为 WINBIO_EXTENDED_ENGINE_INFO 结构指向的缓冲区中返回。 从 Windows 10 开始支持此值。
WINBIO_PROPERTY_EXTENDED_STORAGE_INFO
包含有关连接到特定生物识别单元的存储组件的功能和属性的扩展信息。 属性查询的结果在 PropertyBuffer 参数作为 WINBIO_EXTENDED_STORAGE_INFO 结构指向的缓冲区中返回。 从 Windows 10 开始支持此值。
WINBIO_PROPERTY_EXTENDED_ENROLLMENT_STATUS
包含有关在特定生物识别单元上进行的注册状态的扩展信息。 属性查询的结果在 PropertyBuffer 参数作为 WINBIO_EXTENDED_ENROLLMENT_STATUS 结构指向的缓冲区中返回。 如果未在生物识别单元上进行注册，则返回结构的 TemplateStatus 成员的值为 WINBIO_E_INVALID_OPERATION。 从 Windows 10 开始支持此值。
WINBIO_PROPERTY_ANTI_SPOOF_POLICY
包含特定用户帐户的反欺骗策略的值。 属性操作在 PropertyBuffer 参数作为 WINBIO_ANTI_SPOOF_POLICY 结构指向的缓冲区中返回。 从 Windows 10 开始支持此值。
 

有关这些属性的详细信息，请参阅 WINBIO_PROPERTY常量。

[in, optional] UnitId

标识生物识别单元 的WINBIO_UNIT_ID 值。 可以通过调用 WinBioEnumBiometricUnits 或 WinBioLocateSensor 函数来查找单位标识符。

如果指定 WINBIO_PROPERTY_ANTI_SPOOF_POLICY 作为 PropertyId 参数的值，请为 UnitId 参数指定 0。 如果使用 PropertyId 参数指定任何其他属性，则不能为 UnitId 参数指定 0。

[in, optional] Identity

一种 WINBIO_IDENTITY 结构，提供要获取其反欺骗策略的帐户的 SID（如果将 WINBIO_PROPERTY_ANTI_SPOOF_POLICY 指定为 PropertyId 参数的值）。

如果为 PropertyId 参数指定任何其他值， 则 Identity 参数必须为 NULL。

[in, optional] SubFactor

保留。 这必须 WINBIO_SUBTYPE_NO_INFORMATION。

PropertyBuffer

指向接收属性值的缓冲区的指针的地址。 有关不同属性的此缓冲区的内容的信息，请参阅 PropertyId 参数的属性值说明。

[out, optional] PropertyBufferSize

指向一个变量的指针，该变量接收 PropertyBuffer 参数指向的缓冲区的大小（以字节为单位）。

返回值

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

返回代码 说明
E_HANDLE
 SessionHandle 参数指定的会话句柄无效。
E_POINTER
 Identity、PropertyBuffer 或 PropertyBufferSize 参数不能为 NULL。
E_INVALIDARG
 UnitId、Identity 或 SubFactor 参数不正确。
WINBIO_E_INVALID_PROPERTY_TYPE
 PropertyType 参数的值不正确。
WINBIO_E_INVALID_PROPERTY_ID
 PropertyId 参数的值不正确。
WINBIO_E_LOCK_VIOLATION
 调用方尝试查询位于锁定区域中的属性。
WINBIO_E_UNSUPPORTED_PROPERTY
 正在查询的对象不支持指定的 属性。
WINBIO_E_ENROLLMENT_IN_PROGRESS
 无法完成该操作，因为指定的生物识别单元当前正用于仅) 系统池 (注册事务。

注解

若要同步使用 WinBioGetProperty ，请使用通过调用 WinBioOpenSession 创建的会话句柄调用函数。 函数将一直阻止，直到操作完成或遇到错误。 若要防止在同步使用 WinBioGetProperty 时发生内存泄漏，必须在使用完缓冲区中包含的数据后调用 WinBioFree 以释放 PropertyBuffer 参数指向的内存。

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

  • 如果选择使用回调接收完成通知，则必须实现 PWINBIO_ASYNC_COMPLETION_CALLBACK 函数并将 NotificationMethod 参数设置为 WINBIO_ASYNC_NOTIFY_CALLBACK。
  • 如果选择使用应用程序消息队列接收完成通知，则必须将 NotificationMethod 参数设置为 WINBIO_ASYNC_NOTIFY_MESSAGE。 框架返回指向窗口消息的 LPARAM 字段的WINBIO_ASYNC_RESULT指针。
若要防止在异步使用 WinBioGetProperty 时发生内存泄漏，必须在使用完WINBIO_ASYNC_RESULT结构后调用 WinBioFree 以释放它。 WINBIO_ASYNC_RESULT 结构和属性缓冲区占用单个内存块，因此应用程序只需将 WINBIO_ASYNC_RESULT 结构的地址传递给 WinBioFree。 以这种方式调用 WinBioFree 时， WinBioFree 会自动释放 WINBIO_ASYNC_RESULT 结构和属性缓冲区。 在这种情况下，如果尝试单独释放属性缓冲区，应用程序将停止响应。

要求

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

另请参阅

WinBioFree

WinBioSetProperty