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

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

  • Статья

Асинхронно подключается к поставщику биометрических услуг и одной или нескольким биометрическим единицам. Начиная с Windows 10 сборки 1607 эта функция доступна для использования с мобильным образом. В случае успешного выполнения функция возвращает дескриптор биометрического сеанса. Каждая операция, выполняемая с помощью этого дескриптора, будет выполняться асинхронно, включая WinBioCloseSession, а результаты будут возвращены клиентскому приложению с помощью метода, указанного в параметре NotificationMethod .

Синхронную версию этой функции см. в разделе WinBioOpenSession.

Синтаксис

HRESULT WinBioAsyncOpenSession(
  [in]            WINBIO_BIOMETRIC_TYPE             Factor,
  [in]            WINBIO_POOL_TYPE                  PoolType,
  [in]            WINBIO_SESSION_FLAGS              Flags,
  [in, optional]  WINBIO_UNIT_ID                    *UnitArray,
  [in, optional]  SIZE_T                            UnitCount,
  [in, optional]  GUID                              *DatabaseId,
  [in]            WINBIO_ASYNC_NOTIFICATION_METHOD  NotificationMethod,
  [in, optional]  HWND                              TargetWindow,
  [in, optional]  UINT                              MessageCode,
  [in, optional]  PWINBIO_ASYNC_COMPLETION_CALLBACK CallbackRoutine,
  [in, optional]  PVOID                             UserData,
  [in]            BOOL                              AsynchronousOpen,
  [out, optional] WINBIO_SESSION_HANDLE             *SessionHandle
);

Параметры

[in] Factor

Битовая маска флагов WINBIO_BIOMETRIC_TYPE , указывающая перечисляемые типы биометрических единиц. В настоящее время поддерживается только WINBIO_TYPE_FINGERPRINT .

[in] PoolType

Значение ULONG , указывающее тип биометрических единиц, которые будут использоваться в сеансе. Может иметь одно из следующих значений:

Значение Значение
WINBIO_POOL_SYSTEM
 Сеанс подключается к общей коллекции биометрических единиц, управляемых поставщиком услуг.
WINBIO_POOL_PRIVATE
 Сеанс подключается к коллекции биометрических единиц, которыми управляет вызывающий объект.

[in] Flags

Значение ULONG , указывающее конфигурацию биометрических единиц и характеристики доступа для нового сеанса. Флаги конфигурации указывают общую конфигурацию единиц в сеансе. Флаги доступа указывают, как приложение будет использовать биометрические единицы. Необходимо указать один флаг конфигурации, но его можно объединить с любым флагом доступа.

Значение Значение
WINBIO_FLAG_DEFAULT
 Группа: конфигурация

Биометрические единицы работают способом, указанным во время установки. Это значение необходимо использовать, если параметр PoolTypeWINBIO_POOL_SYSTEM.
WINBIO_FLAG_BASIC
 Группа: конфигурация

Биометрические единицы работают только в качестве базовых устройств захвата. Все операции обработки, сопоставления и хранения выполняются программными подключаемыми модулями.
WINBIO_FLAG_ADVANCED
 Группа: конфигурация

Биометрические единицы используют возможности внутренней обработки и хранения.
WINBIO_FLAG_RAW
 Группа: доступ

Клиентское приложение записывает необработанные биометрические данные с помощью WinBioCaptureSample.
WINBIO_FLAG_MAINTENANCE
 Группа: доступ

Клиент выполняет определяемые поставщиком операции управления с биометрической единицей, вызывая WinBioControlUnitPrivileged.

[in, optional] UnitArray

Указатель на массив биометрических идентификаторов единиц, которые будут включены в сеанс. Для перечисления биометрических единиц можно вызвать WinBioEnumBiometricUnits . Присвойте этому значению значение NULL , если параметр PoolType имеет WINBIO_POOL_SYSTEM.

[in, optional] UnitCount

Значение типа , указывающее количество элементов в массиве, на который указывает параметр UnitArray . Задайте для этого значения нулевое значение, если параметр PoolType имеет значение WINBIO_POOL_SYSTEM.

[in, optional] DatabaseId

Значение типа , указывающее базы данных, которые будут использоваться сеансом. Если параметр PoolType имеет WINBIO_POOL_PRIVATE, необходимо указать GUID установленной базы данных. Если параметр PoolType не WINBIO_POOL_PRIVATE, можно указать одно из следующих общих значений.

Значение Значение
WINBIO_DB_DEFAULT
 Каждая биометрическая единица в пуле датчиков использует базу данных по умолчанию, указанную в конфигурации биометрических единиц по умолчанию. Это значение необходимо указать, если параметр PoolType имеет значение WINBIO_POOL_SYSTEM. Это значение нельзя использовать, если параметр PoolType имеет значение WINBIO_POOL_PRIVATE
WINBIO_DB_BOOTSTRAP
 Это значение можно указать для сценариев перед запуском Windows. Как правило, база данных является частью микросхемы датчика или частью BIOS и может использоваться только для регистрации и удаления шаблона.
WINBIO_DB_ONCHIP
 База данных находится на микросхеме датчика и доступна для регистрации и сопоставления.

[in] NotificationMethod

Указывает, как уведомления о завершении асинхронных операций в этом биометрическом сеансе должны доставляться клиентскому приложению. Это должно быть одно из следующих значений.

Значение Значение
WINBIO_ASYNC_NOTIFY_CALLBACK
 Сеанс вызывает функцию обратного вызова, определенную приложением.
WINBIO_ASYNC_NOTIFY_MESSAGE
 Сеанс отправляет сообщение окна в очередь сообщений приложения.

[in, optional] TargetWindow

Дескриптор окна, которое будет получать уведомления о завершении. Это значение игнорируется, если параметру NotificationMethod не присвоено значение WINBIO_ASYNC_NOTIFY_MESSAGE.

[in, optional] MessageCode

Код сообщения окна, который платформа должна отправить для обозначения уведомлений о завершении. Это значение игнорируется, если параметру NotificationMethod не присвоено значение WINBIO_ASYNC_NOTIFY_MESSAGE. Значение должно находиться в диапазоне WM_APP (0x8000) для 0xBFFF.

Windows Biometric Framework задает значение LPARAM сообщения в адрес структуры WINBIO_ASYNC_RESULT , содержащей результаты операции. Чтобы освободить структуру после завершения использования, необходимо вызвать WinBioFree .

[in, optional] CallbackRoutine

Адрес подпрограммы обратного вызова, вызываемой при запуске операции с использованием дескриптора сеанса. Это значение игнорируется, если параметру NotificationMethod не присвоено значение WINBIO_ASYNC_NOTIFY_CALLBACK.

[in, optional] UserData

Адрес буфера, предоставленного вызывающим объектом. Буфер не изменяется платформой или биометрической единицей. Он возвращается в структуре WINBIO_ASYNC_RESULT . Приложение может использовать эти данные, чтобы определить, какие действия следует выполнить после получения уведомления о завершении, или для хранения дополнительных сведений о запрошенной операции.

[in] AsynchronousOpen

Указывает, следует ли блокировать до открытия сеанса платформы. Если задать значение FALSE , процесс блокируется. Если указать значение TRUE , сеанс открывается асинхронно.

Если для синхронного открытия сеанса платформы задано значение FALSE , функция возвращает объекту успешное или неудачное выполнение непосредственно этой функцией в возвращаемом значении HRESULT . Если сеанс успешно открыт, первое асинхронное событие завершения, получаемое приложением, будет выполняться для асинхронной операции, запрошенной после открытия платформы.

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

[out, optional] SessionHandle

Если функция не выполнена, этот параметр будет иметь значение NULL.

Если сеанс открыт синхронно и успешно, этот параметр будет содержать указатель на дескриптор сеанса.

Если указать, что сеанс открывается асинхронно, этот метод возвращает немедленно, дескриптор сеанса будет иметь значение NULL, и необходимо проверить структуру WINBIO_ASYNC_RESULT , чтобы определить, был ли сеанс успешно открыт.

Возвращаемое значение

Если функция выполняется успешно, она возвращает S_OK. Если функция завершается сбоем, она возвращает значение HRESULT , указывающее на ошибку. Допустимые значения включают, но не ограничиваются, значения, приведенные в следующей таблице. Список распространенных кодов ошибок см. в разделе Общие значения HRESULT.

Код возврата Описание
E_OUTOFMEMORY
 Недостаточно памяти для создания биометрического сеанса.
E_INVALIDARG
 Если для метода уведомления задано значение WINBIO_ASYNC_NOTIFY_MESSAGE, параметр TargetWindow не может иметь значение NULL или HWND_BROADCAST а параметр MessageCode не может быть равен нулю (0).
E_POINTER
 Необходимо задать параметры SessionHandle и AsynchronousOpen .

Если для метода уведомления задано значение WINBIO_ASYNC_NOTIFY_CALLBACK, необходимо также указать адрес функции обратного вызова в параметре CallbackRoutine .
E_ACCESSDENIED
 Параметр Flags содержит флаг WINBIO_FLAG_RAW или WINBIO_FLAG_MAINTENANCE , а вызывающему объекту не предоставлено ни одно из разрешений на доступ.
WINBIO_E_INVALID_UNIT
 Один или несколько биометрических номеров единиц, указанных в параметре UnitArray , недопустимы.
WINBIO_E_NOT_ACTIVE_CONSOLE
 Клиентское приложение выполняется на клиенте удаленного рабочего стола и пытается открыть сеанс системного пула.
WINBIO_E_SENSOR_UNAVAILABLE
 Параметр PoolType имеет значение WINBIO_POOL_PRIVATE и один или несколько запрошенных датчиков в этом пуле недоступны.
WINBIO_E_DISABLED
 Текущая административная политика запрещает использование API Биометрической платформы Windows.

Комментарии

Дескриптор сеанса, возвращаемый функцией WinBioAsyncOpenSession , можно использовать для создания асинхронных уведомлений о завершении для любой из следующих функций:

Дескриптор сеанса, возвращенный WinBioAsyncOpenSession , не может использоваться со следующими функциями: Эти функции, впервые доступные в Windows 7, имеют несовместимую сигнатуру обратного вызова, и их использование в новых приложениях не рекомендуется. Разработчикам, которым нужны асинхронные обратные вызовы, следует использовать WinBioAsyncOpenSession с notificationMethodWINBIO_ASYNC_NOTIFY_CALLBACK.

Параметр AsynchronousOpen определяет, будет ли заблокирована операция открытия. Этот параметр не влияет на поведение завершения последующих вызовов, использующих дескриптор сеанса.

Если для параметра AsynchronousOpen задано значение TRUE, эта функция вернет S_OK сразу после выполнения начальной проверки аргументов. Все ошибки, обнаруженные за пределами этой точки, будут сообщаться вызывающей стороне с помощью метода, заданного параметром NotificationMethod . То есть успешное возвращаемое значение указывает только на то, что параметры WinBioAsyncOpenSession были в порядке, а не на то, что операция открытия выполнена успешно. Чтобы определить, успешно ли выполнена операция открытия, необходимо изучить структуру WINBIO_ASYNC_RESULT .

Требования

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

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

WinBioAsyncOpenFramework

WinBioCloseSession

WinBioOpenSession