Функция WinBioControlUnit (winbio.h)

Статья
03/03/2024

Позволяет вызывающей стороне выполнять определяемые поставщиком операции управления в биометрической единице. Начиная с 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 .

[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 возвращается в обратный вызов приложения или в очередь сообщений приложения в зависимости от значения, заданного в параметре 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

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

WinBioControlUnitPrivileged

WinBioLockUnit

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