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)
Library	Winbio.lib
DLL	Winbio.dll

另请参阅

WinBioOpenSession

WinBioUnregisterEventMonitor

Share via

WinBioRegisterEventMonitor 函数 (winbio.h)

语法

参数

返回值

备注

示例

要求

另请参阅

反馈

反馈

其他资源