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

Статья
08/27/2023

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

Важно

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

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

Синтаксис

HRESULT WinBioLocateSensorWithCallback(
  [in]           WINBIO_SESSION_HANDLE          SessionHandle,
  [in]           PWINBIO_LOCATE_SENSOR_CALLBACK LocateCallback,
  [in, optional] PVOID                          LocateCallbackContext
);

Параметры

[in] SessionHandle

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

[in] LocateCallback

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

[in, optional] LocateCallbackContext

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

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

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

Код возврата	Описание
E_HANDLE	Недопустимый дескриптор сеанса.
E_POINTER	Адрес, указанный параметром LocateCallback , не может иметь значение NULL.

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

Если параметр SessionHandle ссылается на пул системных датчиков, функция обратного вызова не будет вызываться, пока приложение не получит фокус окна и пользователь не предоставит биометрическую выборку. Способ получения фокуса зависит от типа приложения, которое вы пишете. Например, при создании приложения с графическим интерфейсом можно реализовать обработчик сообщений, который захватывает WM_ACTIVATE, WM_SETFOCUS или другое соответствующее сообщение. Если вы пишете приложение CUI, вызовите Метод GetConsoleWindow , чтобы получить дескриптор в окне консоли и передать этот дескриптор в функцию SetForegroundWindow , чтобы принудительно поместить окно консоли на передний план и назначить ему фокус. Если приложение выполняется в отсоединяемом процессе и не имеет окна или является службой Windows, используйте WinBioAcquireFocus и WinBioReleaseFocus для управления фокусом вручную.

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


VOID CALLBACK LocateCallback(
__in_opt PVOID LocateCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId
);

Примеры

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

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

HRESULT LocateSensorWithCallback(BOOL bCancel)
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;

    // 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
            NULL,                       // Database ID
            &sessionHandle              // [out] Session handle
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    wprintf_s(L"\n Calling WinBioLocateSensorWithCallback.");
    hr = WinBioLocateSensorWithCallback(
                sessionHandle,          // Open biometric session
                LocateSensorCallback,   // Callback function
                NULL                    // Optional context
                );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioLocateSensorWithCallback failed.");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Swipe the sensor ...\n");

    // Cancel the 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 
// WinBioLocateSensorWithCallback. The function filters the response 
// from the biometric subsystem and writes a result to the console window.
// 
VOID CALLBACK LocateSensorCallback(
    __in_opt PVOID LocateCallbackContext,
    __in HRESULT OperationStatus,
    __in WINBIO_UNIT_ID UnitId
    )
{
    UNREFERENCED_PARAMETER(LocateCallbackContext);

    wprintf_s(L"\n LocateSensorCallback executing.");

    // A sensor could not be located.
    if (FAILED(OperationStatus))
    {
        wprintf_s(L"\n LocateSensorCallback failed.");
        wprintf_s(L"OperationStatus = 0x%x\n", OperationStatus);
    }
    // A sensor was located.
    else
    {
        wprintf_s(L"\n Selected unit ID: %d\n", UnitId);
    }
}

Требования

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

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

WinBioLocateSensor

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