Поделиться через

Функция 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.

Значение WINBIO_PROPERTY_TYPE_ACCOUNT поддерживается начиная с Windows 10.

[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 , укажите 0 для параметра UnitId . Если вы указываете любое другое свойство с помощью параметра PropertyId , нельзя указать 0 для параметра UnitId .

[in, optional] Identity

Структура WINBIO_IDENTITY , которая предоставляет идентификатор безопасности учетной записи, для которой требуется получить политику защиты от спуфингов, если вы указываете 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 возвращается в обратный вызов приложения или в очередь сообщений приложения в зависимости от значения, заданного в параметре NotificationMethod функции WinBioAsyncOpenSession :

  • Если вы решили получать уведомления о завершении с помощью обратного вызова, необходимо реализовать функцию PWINBIO_ASYNC_COMPLETION_CALLBACK и задать для параметра NotificationMethodзначение WINBIO_ASYNC_NOTIFY_CALLBACK.
  • Если вы решили получать уведомления о завершении с помощью очереди сообщений приложения, необходимо задать для параметра NotificationMethodзначение WINBIO_ASYNC_NOTIFY_MESSAGE. Платформа возвращает указатель WINBIO_ASYNC_RESULT на поле LPARAM сообщения окна.
Чтобы предотвратить утечку памяти при асинхронном использовании WinBioGetProperty , необходимо вызвать WinBioFree , чтобы освободить структуру WINBIO_ASYNC_RESULT после завершения ее использования. Структура WINBIO_ASYNC_RESULT и буфер свойств занимают один блок памяти, поэтому приложению достаточно передать адрес структуры WINBIO_ASYNC_RESULTв WinBioFree. При таком вызове WinBioFreeWinBioFree автоматически освобождает WINBIO_ASYNC_RESULT структуру и буфер свойств. Если вы попытаетесь освободить буфер свойств отдельно в этом случае, приложение перестанет отвечать на запросы.

Требования

Требование Значение
Минимальная версия клиента Windows 7 [только классические приложения]
Минимальная версия сервера Windows Server 2008 R2 [только классические приложения]
Целевая платформа Windows
Header winbio.h (включая Winbio.h)
Библиотека Winbio.lib
DLL Winbio.dll

См. также раздел

WinBioFree

WinBioSetProperty