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 值。
返回代码 | 说明 |
---|---|
|
会话句柄无效。 |
|
EventCallback 参数指定的回调函数的地址不能为 NULL。 |
|
EventMask 参数不能为零,并且不能同时指定WINBIO_EVENT_FP_UNCLAIMED和WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY。 |
|
已注册活动事件监视器。 |
|
服务提供程序不支持事件通知。 |
备注
此函数仅对连接到系统传感器池的会话有效。
事件回调以串行方式传递到客户端应用程序。 因此,在客户端从当前回调返回之前,不会传递后续事件通知。 系统可能会放弃仍在执行回调时发生的事件。 为了避免丢失事件,不应在回调例程中执行任何耗时的工作。
客户端应用程序应准备好在调用 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 |