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

Статья
08/27/2023

Асинхронно захватывает биометрическую выборку и возвращает необработанные или обработанные данные в биометрической информационной записи (BIR). Функция немедленно возвращается вызывающей стороне, захватывает пример в отдельном потоке и вызывает определяемую приложением функцию обратного вызова для обновления состояния операции.

Важно

Начиная с Windows 8 рекомендуется больше не использовать эту функцию для запуска асинхронной операции. Вместо этого выполните указанные ниже действия.

Реализуйте функцию PWINBIO_ASYNC_COMPLETION_CALLBACK для получения уведомления по завершении операции.
Вызовите функцию WinBioAsyncOpenSession . Передайте адрес обратного вызова в параметре CallbackRoutine . Передайте WINBIO_ASYNC_NOTIFY_CALLBACK в параметре NotificationMethod . Получение асинхронного дескриптора сеанса.
Используйте асинхронный дескриптор сеанса для вызова WinBioCaptureSample. Когда операция завершится, Windows Biometric Framework выделит и инициализирует структуру WINBIO_ASYNC_RESULT с результатами и вызовет обратный вызов с указателем на структуру результатов.
Вызовите WinBioFree из реализации обратного вызова, чтобы освободить структуру WINBIO_ASYNC_RESULT после завершения ее использования.

Синтаксис

HRESULT WinBioCaptureSampleWithCallback(
  [in]           WINBIO_SESSION_HANDLE    SessionHandle,
  [in]           WINBIO_BIR_PURPOSE       Purpose,
  [in]           WINBIO_BIR_DATA_FLAGS    Flags,
  [in]           PWINBIO_CAPTURE_CALLBACK CaptureCallback,
  [in, optional] PVOID                    CaptureCallbackContext
);

Параметры

[in] SessionHandle

Значение WINBIO_SESSION_HANDLE , определяющее открытый биометрический сеанс.

[in] Purpose

Битовая маска WINBIO_BIR_PURPOSE, указывающая предполагаемое использование образца. Это может быть побитовое ИЛИ следующих значений:

WINBIO_PURPOSE_VERIFY
WINBIO_PURPOSE_IDENTIFY
WINBIO_PURPOSE_ENROLL
WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[in] Flags

Значение типа , указывающее тип обработки, применяемой к захваченной выборке. Это может быть побитовое ИЛИ следующих флагов уровня безопасности и обработки:

WINBIO_DATA_FLAG_PRIVACY

Зашифруйте пример.

WINBIO_DATA_FLAG_INTEGRITY

Подпишите пример или защитите его с помощью кода проверки подлинности сообщения (MAC).

WINBIO_DATA_FLAG_SIGNED

Если этот флаг и WINBIO_DATA_FLAG_INTEGRITYflag установлены, подпишите пример. Если этот флаг не задан, но установлен флаг WINBIO_DATA_FLAG_INTEGRITY, вычислить MAC-файл.

WINBIO_DATA_FLAG_RAW

Возвращает образец точно так, как он был захвачен датчиком.

WINBIO_DATA_FLAG_INTERMEDIATE

Верните образец после его очистки и фильтрации.

WINBIO_DATA_FLAG_PROCESSED

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

[in] CaptureCallback

Адрес функции обратного вызова, которая будет вызываться функцией WinBioCaptureSampleWithCallback при успешном или неудачном выполнении операции захвата. Необходимо создать обратный вызов.

[in, optional] CaptureCallbackContext

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

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

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

Код возврата	Описание
E_ACCESSDENIED	Вызывающий объект не имеет разрешения на запись необработанных выборок или сеанс не был открыт с помощью флага WINBIO_FLAG_RAW .
E_HANDLE	Недопустимый дескриптор сеанса.
E_NOTIMPL	Биометрический блок не поддерживает запрошенную операцию.
E_POINTER	Указатели UnitId, Sample, SampleSize и RejectDetail не могут иметь значение NULL.
WINBIO_E_ENROLLMENT_IN_PROGRESS	Не удалось завершить операцию, так как биометрическая единица в настоящее время используется для транзакции регистрации (только системный пул).

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

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

Вызывающие абоненты отвечают за освобождение структуры WINBIO_BIR , возвращаемой параметром Sample .

Подпрограмма обратного вызова должна иметь следующую сигнатуру:

VOID CALLBACK CaptureCallback(
__in_opt PVOID CaptureCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in_bcount(SampleSize) PWINBIO_BIR Sample,
__in SIZE_T SampleSize,
__in WINBIO_REJECT_DETAIL RejectDetail
);

Примеры

В следующем примере кода образец захватывается асинхронно путем вызова WinBioCaptureSampleWithCallback и передачи указателя на пользовательскую функцию обратного вызова. Также показана функция обратного вызова CaptureSampleCallback. Ссылка на статическую библиотеку Winbio.lib и включение следующих файлов заголовков:

Windows.h
Stdio.h
Conio.h
Winbio.h

HRESULT CaptureSampleWithCallback(BOOL bCancel)
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_RAW,            // Raw access
            NULL,                       // Array of biometric unit IDs
            0,                          // Count of biometric unit IDs
            WINBIO_DB_DEFAULT,          // Default database
            &sessionHandle              // [out] Session handle
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Capture a biometric sample asynchronously.
    wprintf_s(L"\n Calling WinBioCaptureSampleWithCallback ");
    hr = WinBioCaptureSampleWithCallback(
            sessionHandle,                  // Open session handle
            WINBIO_NO_PURPOSE_AVAILABLE,    // Intended use of the sample
            WINBIO_DATA_FLAG_RAW,           // Sample format
            CaptureSampleCallback,          // Callback function
            NULL                            // Optional context
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Swipe the sensor ...\n");

    // Cancel the capture process if the bCancel flag is set.
    if (bCancel)
    {
        wprintf_s(L"\n Starting CANCEL timer...");
        Sleep( 7000 );

        wprintf_s(L"\n Calling WinBioCancel\n");
        hr = WinBioCancel( sessionHandle );
        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioCancel failed. hr = 0x%x\n", hr);
            goto e_Exit;
        }
    }

    // Wait for the asynchronous capture process to complete 
    // or be canceled.
    hr = WinBioWait( sessionHandle );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioWait failed. hr = 0x%x\n", hr);
    }

e_Exit:

    if (sessionHandle != NULL)
    {
        WinBioCloseSession(sessionHandle);
        sessionHandle = NULL;
    }

    wprintf_s(L"\n Press any key to exit...");
    _getch();

    return hr;
}

//------------------------------------------------------------------------
// The following function is the callback for WinBioCaptureSampleWithCallback.
// The function filters the response from the biometric subsystem and 
// writes a result to the console window.
//
VOID CALLBACK CaptureSampleCallback(
    __in_opt PVOID CaptureCallbackContext,
    __in HRESULT OperationStatus,
    __in WINBIO_UNIT_ID UnitId,
    __in_bcount(SampleSize) PWINBIO_BIR Sample,
    __in SIZE_T SampleSize,
    __in WINBIO_REJECT_DETAIL RejectDetail
    )
{
    UNREFERENCED_PARAMETER(CaptureCallbackContext);

    wprintf_s(L"\n CaptureSampleCallback executing");
    wprintf_s(L"\n Swipe processed - Unit ID: %d", UnitId);

    if (FAILED(OperationStatus))
    {
        if (OperationStatus == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
         }
        else
        {
            wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
            wprintf_s(L" OperationStatus = 0x%x\n", OperationStatus);
        }
        goto e_Exit;
    }

    wprintf_s(L"\n Captured %d bytes.\n", SampleSize);

e_Exit:

    if (Sample != NULL)
    {
        WinBioFree(Sample);
        Sample = NULL;
    }
}

Требования

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

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

WinBioCaptureSample

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