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

Статья
08/27/2023

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

Важно

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

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

Синтаксис

HRESULT WinBioIdentifyWithCallback(
  [in]           WINBIO_SESSION_HANDLE     SessionHandle,
  [in]           PWINBIO_IDENTIFY_CALLBACK IdentifyCallback,
  [in, optional] PVOID                     IdentifyCallbackContext
);

Параметры

[in] SessionHandle

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

[in] IdentifyCallback

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

[in, optional] IdentifyCallbackContext

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

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

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

Код возврата	Описание
E_HANDLE	Недопустимый дескриптор сеанса.
E_POINTER	Параметры SessionHandle и IdentifyCallback не могут иметь значение NULL.

В следующем примере кода вызывается WinBioIdentifyWithCallback для идентификации пользователя с помощью биометрического сканирования. WinBioIdentifyWithCallback — это асинхронная функция, которая настраивает биометрическую подсистему для обработки биометрических входных данных в другом потоке. Затем выходные данные биометрической подсистемы отправляются в пользовательскую функцию обратного вызова с именем IdentifyCallback. Ссылка на статическую библиотеку Winbio.lib и включение следующих файлов заголовков:

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

HRESULT IdentifyWithCallback(BOOL bCancel)
{
    // Declare variables.
    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_DEFAULT,        // Configuration and access 
            NULL,                       // Array of biometric unit IDs 
            0,                          // Count of biometric unit IDs 
            WINBIO_DB_DEFAULT,          // Database ID 
            &sessionHandle              // [out] Session handle
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Call WinBioIdentifyWithCallback. The method is asynchronous
    // and returns immediately.
    wprintf_s(L"\n Calling WinBioIdentifyWithCallback");
    wprintf_s(L"\n Swipe the sensor ...\n");
    hr = WinBioIdentifyWithCallback( 
            sessionHandle,              // Open biometric session
            IdentifyCallback,           // Callback function
            NULL                        // Optional context
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioIdentifyWithCallback failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Cancel user identification if the bCancel flag is set.
    if (bCancel)
    {
        wprintf_s(L"\n Starting CANCEL timer...\n");
        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 identification 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)
    {
       wprintf_s(L"\n Closing the session.\n");

        hr = WinBioCloseSession(sessionHandle);
        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioCloseSession failed. hr = 0x%x\n", hr);
        }
        sessionHandle = NULL;
    }

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

    return hr;
}

//------------------------------------------------------------------------
// The following function is the callback for WinBioIdentifyWithCallback.
// The function filters the response from the biometric subsystem and 
// writes a result to the console window.
// 
VOID CALLBACK IdentifyCallback(
    __in_opt PVOID IdentifyCallbackContext,
    __in HRESULT OperationStatus,
    __in WINBIO_UNIT_ID UnitId,
    __in WINBIO_IDENTITY *Identity,
    __in WINBIO_BIOMETRIC_SUBTYPE SubFactor,
    __in WINBIO_REJECT_DETAIL RejectDetail
    )
{
    UNREFERENCED_PARAMETER(IdentifyCallbackContext);
    UNREFERENCED_PARAMETER(Identity);

    wprintf_s(L"\n IdentifyCallback executing");
    wprintf_s(L"\n Swipe processed for unit ID %d\n", UnitId);

    // The attempt to process the fingerprint failed.
    if (FAILED(OperationStatus))
    {
        if (OperationStatus == WINBIO_E_UNKNOWN_ID)
        {
            wprintf_s(L"\n Unknown identity.\n");
        }
        else if (OperationStatus == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
        }
        else
        {
            wprintf_s(L"IdentifyCallback failed.");
            wprintf_s(L"OperationStatus = 0x%x\n", OperationStatus); 
        }
    }
    // Processing succeeded and the finger swiped is written
    // to the console window.
    else
    {
        wprintf_s(L"\n The following finger was used:");
        switch (SubFactor)
        {
            case WINBIO_SUBTYPE_NO_INFORMATION:
                wprintf_s(L"\n No information\n");
                break;
            case WINBIO_ANSI_381_POS_RH_THUMB:
                wprintf_s(L"\n RH thumb\n");
                break;
            case WINBIO_ANSI_381_POS_RH_INDEX_FINGER:
                wprintf_s(L"\n RH index finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER:
                wprintf_s(L"\n RH middle finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_RING_FINGER:
                wprintf_s(L"\n RH ring finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_LITTLE_FINGER:
                wprintf_s(L"\n RH little finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_THUMB:
                wprintf_s(L"\n LH thumb\n");
                break;
            case WINBIO_ANSI_381_POS_LH_INDEX_FINGER:
                wprintf_s(L"\n LH index finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER:
                wprintf_s(L"\n LH middle finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_RING_FINGER:
                wprintf_s(L"\n LH ring finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_LITTLE_FINGER:
                wprintf_s(L"\n LH little finger\n");
                break;
            case WINBIO_SUBTYPE_ANY:
                wprintf_s(L"\n Any finger\n");
                break;
            default:
                break;
        }
    }
}

Требования


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

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

WinBioIdentify

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

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

Синтаксис

Параметры

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

Комментарии

Примеры

Требования

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

Обратная связь

Дополнительные ресурсы