WinBioLocateSensorWithCallback 函数 (winbio.h)

项目
03/03/2024

异步检索用户以交互方式选择的生物识别单元的 ID 号。函数立即返回给调用方，在单独的线程上处理，并通过调用应用程序定义的回调函数报告所选生物识别单元。

重要说明

建议从 Windows 8 开始，不再使用此函数来启动异步操作。请改为执行以下操作：

实现 PWINBIO_ASYNC_COMPLETION_CALLBACK 函数，以在操作完成时接收通知。
调用 WinBioAsyncOpenSession 函数。在 CallbackRoutine 参数中传递回调的地址。在 NotificationMethod 参数中传递WINBIO_ASYNC_NOTIFY_CALLBACK。检索异步会话句柄。
使用异步会话句柄调用 WinBioLocateSensor。操作完成后，Windows 生物识别框架将使用结果分配和初始化 WINBIO_ASYNC_RESULT 结构，并使用指向结果结构的指针调用回调。
从回调实现调用 WinBioFree ，以在使用完 WINBIO_ASYNC_RESULT 结构后释放它。

语法

HRESULT WinBioLocateSensorWithCallback(
  [in]           WINBIO_SESSION_HANDLE          SessionHandle,
  [in]           PWINBIO_LOCATE_SENSOR_CALLBACK LocateCallback,
  [in, optional] PVOID                          LocateCallbackContext
);

参数

[in] SessionHandle

标识打开的生物识别会话 的WINBIO_SESSION_HANDLE 值。

[in] LocateCallback

当传感器位置成功或失败时， WinBioLocateSensorWithCallback 函数将调用的回调函数的地址。必须创建回调。

[in, optional] LocateCallbackContext

传递给 其 LocateCallbackContext 参数中的回调函数的应用程序定义数据结构的地址。此结构可以包含自定义回调函数旨在处理的任何数据。

返回值

如果函数成功，则返回 S_OK。如果函数失败，它将返回指示错误的 HRESULT 值。可能的值包括（但并不限于）下表中的项。有关常见错误代码的列表，请参阅常见 HRESULT 值。

返回代码	说明
E_HANDLE	会话句柄无效。
E_POINTER	由 LocateCallback 参数指定的地址不能为 NULL。

注解

可以在具有多个传感器的系统上使用此函数来确定用户首选注册的传感器。此函数不返回任何标识信息。提供它只是为了指示用户传感器的选择。

如果 SessionHandle 参数引用系统传感器池，则在应用程序获取窗口焦点并且用户提供生物识别示例之前，不会调用回调函数。获取焦点的方式取决于正在编写的应用程序类型。例如，如果要创建 GUI 应用程序，则可以实现捕获WM_ACTIVATE、WM_SETFOCUS或其他相应消息的消息处理程序。如果要编写 CUI 应用程序，请调用 GetConsoleWindow 检索控制台窗口的句柄，并将该句柄传递给 SetForegroundWindow 函数，以强制控制台窗口进入前台并为其分配焦点。如果应用程序在分离进程中运行，并且没有窗口或是 Windows 服务，请使用 WinBioAcquireFocus 和 WinBioReleaseFocus 手动控制焦点。

回调例程必须具有以下签名：


VOID CALLBACK LocateCallback(
__in_opt PVOID LocateCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId
);

示例

以下函数调用 WinBioLocateSensorWithCallback 来查找生物识别传感器。 WinBioLocateSensorWithCallback 是一个异步函数，用于配置生物识别子系统以在另一个线程上定位传感器。生物识别子系统的输出将发送到名为 LocateSensorCallback 的自定义回调函数。链接到 Winbio.lib 静态库并包含以下头文件：

Windows.h
Stdio.h
Conio.h
Winbio.h

HRESULT LocateSensorWithCallback(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;
    }

    wprintf_s(L"\n Calling WinBioLocateSensorWithCallback.");
    hr = WinBioLocateSensorWithCallback(
                sessionHandle,          // Open biometric session
                LocateSensorCallback,   // Callback function
                NULL                    // Optional context
                );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioLocateSensorWithCallback failed.");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Swipe the sensor ...\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 the asynchronous identification process to complete 
    // or be canceled.
    hr = WinBioWait( sessionHandle );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioWait failed. 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 Hit any key to exit...");
    _getch();

    return hr;
}

//------------------------------------------------------------------------
// The following function is the callback for 
// WinBioLocateSensorWithCallback. The function filters the response 
// from the biometric subsystem and writes a result to the console window.
// 
VOID CALLBACK LocateSensorCallback(
    __in_opt PVOID LocateCallbackContext,
    __in HRESULT OperationStatus,
    __in WINBIO_UNIT_ID UnitId
    )
{
    UNREFERENCED_PARAMETER(LocateCallbackContext);

    wprintf_s(L"\n LocateSensorCallback executing.");

    // A sensor could not be located.
    if (FAILED(OperationStatus))
    {
        wprintf_s(L"\n LocateSensorCallback failed.");
        wprintf_s(L"OperationStatus = 0x%x\n", OperationStatus);
    }
    // A sensor was located.
    else
    {
        wprintf_s(L"\n Selected unit ID: %d\n", UnitId);
    }
}

要求

要求	值
最低受支持的客户端	Windows 7 [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 R2 [仅限桌面应用]
目标平台	Windows
标头	winbio.h (包括 Winbio.h)
Library	Winbio.lib
DLL	Winbio.dll

另请参阅

WinBioLocateSensor

通过

WinBioLocateSensorWithCallback 函数 (winbio.h)

语法

参数

返回值

注解

示例

要求

另请参阅

反馈

其他资源