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 パラメーターを 0 にすることはできません。また、WINBIO_EVENT_FP_UNCLAIMEDとWINBIO_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

WinBioRegisterEventMonitor 関数 (winbio.h)

構文

パラメーター

戻り値

解説

例

要件

関連項目

フィードバック

フィードバック

その他のリソース