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

Функция 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 Framework в функцию обратного вызова, чтобы указать, что пальцем проводите пальцем, но не пытается определить отпечатки пальцев.

• WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY

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

[in] EventCallback

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

[in] EventCallbackContext

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

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

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

Замечания

Эта функция действительна только для сеансов, подключенных к пулу системных датчиков.

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

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

После запуска монитора событий сеанс, с которым связан монитор, не сможет обрабатывать другие вызовы API Windows Биометрических платформ, пока монитор событий не будет остановлен. Если приложению необходимо выполнять другие вызовы 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;
    }
}

Требования

См. также

WinBioOpenSession

WinBioUnregisterEventMonitor