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 生物特徵辨識架構會呼叫回呼函式，指出已發生手指撥動，但不會嘗試識別指紋。

WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY

感應器偵測到應用程式未要求的手指撥動，或要求的應用程式沒有視窗焦點。 Windows 生物特徵辨識架構會嘗試識別指紋，並將該程式的結果傳遞至您的回呼函式。

[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 引數中傳回的結構。若無法這麼做，會導致呼叫進程發生記憶體流失。

啟動事件監視器之後，監視相關聯的會話將無法處理其他 Windows 生物特徵辨識架構 API 呼叫，直到事件監視器停止為止。如果您的應用程式需要在接收事件監視器通知的同時執行其他 API 呼叫，您應該開啟兩個會話，一個用於事件監視器，另一個用於其他作業。

呼叫 WinBioUnregisterEventMonitor 以停止將事件通知傳送至回呼函式。

如果應用程式註冊 WinBio 事件監視器，並在睡眠/喚醒週期期間讓該監視器保持作用中，則實作生物特徵辨識開機前驗證的系統 (PBA) /單一登入功能不一定會運作。問題在於，在系統生物特徵辨識認證提供者有機會執行第一個 WinBioIdentify 作業之前，事件監視器會攔截 PBA 生物特徵辨識呼叫。使用 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
標頭	winbio.h (包含 Winbio.h)
程式庫	Winbio.lib
Dll	Winbio.dll

另請參閱

WinBioOpenSession

WinBioUnregisterEventMonitor

共用方式為

winBioRegisterEventMonitor 函式 (winbio.h)

語法

參數

傳回值

備註

範例

規格需求

另請參閱

意見反應

其他資源