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

[in] Flags

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

[in, optional] UnitArray

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

[in, optional] UnitCount

Значение, указывающее количество элементов в массиве, на которое указывает параметр UnitArray . Установите это значение равным нулю, если параметр PoolTypeWINBIO_POOL_SYSTEM.

[in, optional] DatabaseId

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

[in] NotificationMethod

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

[in, optional] TargetWindow

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

[in, optional] MessageCode

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

В Windows Биометрические платформы значение 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".

Замечания

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

• WinBioCancel
• WinBioCaptureSample
• WinBioCloseSession
• WinBioControlUnit
• WinBioControlUnitPrivileged
• WinBioDeleteTemplate
• WinBioEnrollBegin
• WinBioEnrollCapture
• WinBioEnrollCommit
• WinBioEnrollDiscard
• WinBioEnumEnrollments
• WinBioGetProperty
• WinBioIdentify
• WinBioLocateSensor
• WinBioLockUnit
• WinBioLogonIdentifiedUser
• WinBioRegisterEventMonitor
• WinBioUnlockUnit
• WinBioUnregisterEventMonitor
• WinBioVerify
• WinBioWait

• WinBioCaptureSampleWithCallback
• WinBioEnrollCaptureWithCallback
• WinBioIdentifyWithCallback
• WinBioIdentifyWithCallback

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

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

Требования

См. также

WinBioAsyncOpenFramework

WinBioCloseSession

WinBioOpenSession