Share via

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

[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 .

Необходимо вызвать WinBioLockUnit перед вызовом WinBioControlUnitPrivileged. Функция WinBioLockUnit создает заблокированный регион, в котором можно безопасно выполнять операции, определяемые поставщиком.

Для успешного вызова этой функции необходимо открыть дескриптор сеанса, указав WINBIO_FLAG_MAINTENANCE. Только учетные записи администраторов и локальных систем имеют необходимые привилегии.

Чтобы использовать WinBioControlUnitPrivileged синхронно, вызовите функцию с дескриптором сеанса, созданным путем вызова WinBioOpenSession. Функция блокируется, пока операция не завершится или не возникнет ошибка.

Чтобы использовать WinBioControlUnitPrivileged асинхронно, вызовите функцию с дескриптором сеанса, созданным путем вызова WinBioAsyncOpenSession. Платформа выделяет структуру WINBIO_ASYNC_RESULT и использует ее для возврата сведений об успешном или неудачном выполнении операции. Структура WINBIO_ASYNC_RESULT возвращается в обратный вызов приложения или в очередь сообщений приложения в зависимости от значения, заданного в параметре NotificationMethod функции WinBioAsyncOpenSession .

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

Требования

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

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

WinBioControlUnit

WinBioLockUnit