共用方式為


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

  • 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_UNCLAIMEDWINBIO_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