次の方法で共有


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 パラメーターを 0 にすることはできません。また、WINBIO_EVENT_FP_UNCLAIMEDWINBIO_EVENT_FP_UNCLAIMED_IDENTIFYの両方を同時に指定することはできません。
WINBIO_E_EVENT_MONITOR_ACTIVE
アクティブなイベント モニターが既に登録されています。
WINBIO_E_INVALID_OPERATION
サービス プロバイダーはイベント通知をサポートしていません。

解説

この関数は、システム センサー プールに接続されているセッションでのみ有効です。

イベント コールバックは、クライアント アプリケーションに順次配信されます。 そのため、クライアントが現在のコールバックから戻るまで、後続のイベント通知は配信されません。 コールバックの実行中に発生するイベントは、システムによって破棄される可能性があります。 イベントが失われるのを防ぐために、コールバック ルーチンで時間のかかる作業を実行しないでください。

クライアント アプリケーションは、 WinBioRegisterEventMonitor が呼び出されるとすぐにイベントを受信するように準備する必要があります。 アプリケーションは WinBioFree を 呼び出して、コールバックの Event 引数で返される構造体を解放する必要があります。 これを行わないと、呼び出し元プロセスでメモリ リークが発生します。

イベント モニターが開始されると、モニターが関連付けられているセッションは、イベント モニターが停止するまで、他の Windows 生体認証フレームワーク API 呼び出しを処理できなくなります。 イベント モニター通知の受信中にアプリケーションで他の API 呼び出しを実行する必要がある場合は、イベント モニター用と他の操作用の 2 つのセッションを開く必要があります。

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 を含む)
Library Winbio.lib
[DLL] Winbio.dll

関連項目

WinBioOpenSession

WinBioUnregisterEventMonitor