WinBioRegisterEventMonitor 函数 （winbio.h）

WinBioRegisterEventMonitor 函数注册回调函数，以接收与打开会话关联的服务提供商的事件通知。

Syntax

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 值。

注解

此函数仅适用于连接到系统传感器池的会话。

事件回调将串行传送到客户端应用程序。 因此，在客户端从当前回调返回之前，不会传递后续事件通知。 系统可能会放弃回调仍在执行时发生的事件。 为了避免丢失事件，不应在回调例程中执行任何耗时的工作。

调用 WinBioRegisterEventMonitor 后，客户端应用程序应立即准备好接收事件。 应用程序必须调用 WinBioFree 才能释放回调 事件 参数中返回的结构。 否则会导致调用过程中出现内存泄漏。

启动事件监视器后，与监视器关联的会话将无法处理其他 Windows 生物识别框架 API 调用，直到事件监视器停止为止。 如果应用程序需要在仍接收事件监视器通知的同时执行其他 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