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

Статья
08/27/2023

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

Синтаксис

HRESULT WinBioRegisterEventMonitor(
  [in] WINBIO_SESSION_HANDLE  SessionHandle,
  [in] WINBIO_EVENT_TYPE      EventMask,
  [in] PWINBIO_EVENT_CALLBACK EventCallback,
  [in] PVOID                  EventCallbackContext
);

Параметры

[in] SessionHandle

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

[in] EventMask

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

WINBIO_EVENT_FP_UNCLAIMED

Датчик обнаружил пальцем, который не был запрошен приложением, или приложение не имеет фокуса окна. Windows Biometric Framework вызывает функцию обратного вызова, чтобы указать, что произошло прокрутка пальца, но не пытается идентифицировать отпечаток.

WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY

Датчик обнаружил пальцем, который не был запрошен приложением, или приложение не имеет фокуса окна. Windows Biometric Framework пытается идентифицировать отпечаток пальца и передает результат этого процесса в функцию обратного вызова.

[in] EventCallback

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

[in] EventCallbackContext

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

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

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

Код возврата	Описание
E_HANDLE	Недопустимый дескриптор сеанса.
E_POINTER	Адрес функции обратного вызова, заданный параметром EventCallback , не может иметь значение NULL.
E_INVALIDARG	Параметр EventMask не может быть равен нулю, и нельзя указать одновременно WINBIO_EVENT_FP_UNCLAIMED и WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY .
WINBIO_E_EVENT_MONITOR_ACTIVE	Активный монитор событий уже зарегистрирован.
WINBIO_E_INVALID_OPERATION	Поставщик услуг не поддерживает уведомление о событиях.

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

Клиентское приложение должно быть готово к получению событий сразу после вызова WinBioRegisterEventMonitor . Приложение должно вызвать WinBioFree , чтобы освободить структуру, возвращаемую в аргументе Event обратного вызова. Невыполнение этого действия приведет к утечке памяти в вызывающем процессе.

После запуска монитора событий сеанс, с которым связан монитор, не сможет обрабатывать другие вызовы API Windows Biometric Framework, пока монитор событий не будет остановлен. Если приложению необходимо выполнять другие вызовы API, по-прежнему получая уведомления монитора событий, следует открыть два сеанса : один для монитора событий, а другой для других операций.

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

Если приложение регистрирует монитор событий WinBio и оставляет его активным во время сна и пробуждения, системы, реализующие биометрические функции проверки подлинности перед загрузкой (PBA) и единого входа, могут работать не всегда. Проблема заключается в том, что биометрический вызов PBA перехватывается монитором событий до того, как поставщик биометрических учетных данных системы получит возможность выполнить свою первую операцию WinBioIdentify . Приложения, использующие функцию мониторинга событий WinBio , должны отменить регистрацию своих мониторов до того, как система переходит в спящий режим, и повторно зарегистрировать их после пробуждения системы. Дополнительные сведения об обработке событий во время изменения состояния питания см. в разделе Сведения об управлении питанием.

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


VOID CALLBACK EventCallback(
__in_opt PVOID EventCallbackContext,
__in HRESULT OperationStatus,
__in PWINBIO_EVENT Event
);

Примеры

Следующая функция регистрирует монитор событий, вызывая функцию WinBioRegisterEventMonitor и передавая адрес подпрограммы обратного вызова. Обратный вызов, также включенный, получает уведомления о событиях от биометрической платформы Windows. Ссылка на статическую библиотеку Winbio.lib и включение следующих файлов заголовков:

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

HRESULT RegisterSystemEventMonitor(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;
    }

    // Call the WinBioRegisterEventMonitor function.
    wprintf_s(L"\n Calling WinBioRegisterEventMonitor.\n");
    hr = WinBioRegisterEventMonitor(
            sessionHandle,              // Open session handle
            WINBIO_EVENT_FP_UNCLAIMED,  // Events to monitor
            EventMonitorCallback,       // Callback function
            NULL                        // Optional context.
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioRegisterEventMonitor failed.");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Waiting for an event.\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 an event to happen.
    //wprintf_s(L"\n Swipe the sensor to receive an event notice ");
    //wprintf_s(L"\n or press any key to stop waiting...\n");
    wprintf_s(L"\n Swipe the sensor one or more times ");
    wprintf_s(L"to generate events.");
    wprintf_s(L"\n When done, press a key to exit...\n");
    _getch();

    // Unregister the event monitor.
    wprintf_s(L"\n Calling WinBioUnregisterEventMonitor\n");
    hr = WinBioUnregisterEventMonitor( sessionHandle);
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioUnregisterEventMonitor failed.");
        wprintf_s(L"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 Press any key to exit...");
    _getch();

    return hr;
}

//------------------------------------------------------------------------
// The following function is the callback for WinBioRegisterEventMonitor.
// The function filters any event notice from the biometric subsystem and 
// writes a result to the console window.
// 
VOID CALLBACK EventMonitorCallback(
    __in_opt PVOID EventCallbackContext,
    __in HRESULT OperationStatus,
    __in PWINBIO_EVENT Event
    )
{
    UNREFERENCED_PARAMETER(EventCallbackContext);

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

    // Failure.
    if (FAILED(OperationStatus))
    {
        wprintf_s(L"\n EventMonitorCallback failed. ");
        wprintf_s(L" OperationStatus = 0x%x\n", OperationStatus);
        goto e_Exit;
    }

    // An event notice was received.
    if (Event != NULL)
    {
        wprintf_s(L"\n MonitorEvent: ");
        switch (Event->Type)
        {
            case WINBIO_EVENT_FP_UNCLAIMED:
                wprintf_s(L"WINBIO_EVENT_FP_UNCLAIMED");
                wprintf_s(L"\n Unit ID: %d", 
                          Event->Parameters.Unclaimed.UnitId);
                wprintf_s(L"\n Reject detail: %d\n", 
                          Event->Parameters.Unclaimed.RejectDetail);
                break;

            case WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY:
                wprintf_s(L"WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY");
                wprintf_s(L"\n Unit ID: %d", 
                          Event->Parameters.UnclaimedIdentify.UnitId);
                wprintf_s(L"\n Reject detail: %d\n", 
                          Event->Parameters.UnclaimedIdentify.RejectDetail);
                break;

            case WINBIO_EVENT_ERROR:
                wprintf_s(L"WINBIO_EVENT_ERROR\n");
                break;

            default:
                wprintf_s(L"(0x%08x - Invalid type)\n", Event->Type);
                break;
        }
    }

e_Exit:

    if (Event != NULL)
    {
        //wprintf_s(L"\n Press any key to continue...\n");
        WinBioFree(Event);
        Event = NULL;
    }
}

Требования


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

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

WinBioOpenSession

WinBioUnregisterEventMonitor

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