WinBioCaptureSampleWithCallback 函数 (winbio.h)

项目
03/13/2024

异步捕获生物识别样本，并在 BIR) (生物识别信息记录中返回原始或已处理的数据。函数立即返回给调用方，在单独的线程上捕获示例，并调用应用程序定义的回调函数以更新操作状态。

重要说明

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

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

语法

HRESULT WinBioCaptureSampleWithCallback(
  [in]           WINBIO_SESSION_HANDLE    SessionHandle,
  [in]           WINBIO_BIR_PURPOSE       Purpose,
  [in]           WINBIO_BIR_DATA_FLAGS    Flags,
  [in]           PWINBIO_CAPTURE_CALLBACK CaptureCallback,
  [in, optional] PVOID                    CaptureCallbackContext
);

参数

[in] SessionHandle

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

[in] Purpose

指定示例的预期用途 的WINBIO_BIR_PURPOSE 位掩码。这可以是以下值的按位 OR ：

WINBIO_PURPOSE_VERIFY
WINBIO_PURPOSE_IDENTIFY
WINBIO_PURPOSE_ENROLL
WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[in] Flags

一个值，该值指定要应用于捕获的样本的处理类型。这可以是以下安全和处理级别标志的按位 OR ：

WINBIO_DATA_FLAG_PRIVACY

加密示例。

WINBIO_DATA_FLAG_INTEGRITY

使用消息身份验证代码 (MAC) 对示例进行签名或对其进行保护。

WINBIO_DATA_FLAG_SIGNED

如果设置了此标志和WINBIO_DATA_FLAG_INTEGRITYflag，请对示例进行签名。如果未设置此标志，但设置了WINBIO_DATA_FLAG_INTEGRITY标志，则计算 MAC。

WINBIO_DATA_FLAG_RAW

返回与传感器捕获的样本完全相同的样本。

WINBIO_DATA_FLAG_INTERMEDIATE

清理和筛选后返回示例。

WINBIO_DATA_FLAG_PROCESSED

在准备好用于 Purpose 参数指定的用途后，返回该示例。

[in] CaptureCallback

捕获操作成功或失败时由 WinBioCaptureSampleWithCallback 函数调用的回调函数的地址。必须创建回调。

[in, optional] CaptureCallbackContext

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

返回值

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

返回代码	说明
E_ACCESSDENIED	调用方无权捕获原始样本，或者未使用 WINBIO_FLAG_RAW 标志打开会话。
E_HANDLE	会话句柄无效。
E_NOTIMPL	生物识别单元不支持请求的操作。
E_POINTER	UnitId、Sample、SampleSize 和 RejectDetail 指针不能为 NULL。
WINBIO_E_ENROLLMENT_IN_PROGRESS	无法完成该操作，因为生物识别单元当前仅用于系统池 () 注册事务。

注解

WinBioCaptureSampleWithCallback 函数以异步方式捕获样本。若要成功调用此函数，必须通过指定 WINBIO_FLAG_RAW打开会话句柄。只有管理员和本地系统帐户具有必要的权限。

“用途”和“标志”参数的有效组合取决于所使用的生物识别单元的功能。请参阅供应商传感器文档，确定支持的组合以及它们如何影响捕获的数据。

调用方负责释放 Sample 参数返回的WINBIO_BIR结构。

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

VOID CALLBACK CaptureCallback(
__in_opt PVOID CaptureCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in_bcount(SampleSize) PWINBIO_BIR Sample,
__in SIZE_T SampleSize,
__in WINBIO_REJECT_DETAIL RejectDetail
);

示例

下面的代码示例通过调用 WinBioCaptureSampleWithCallback 并将指针传递给自定义回调函数来异步捕获示例。还显示了回调函数 CaptureSampleCallback。链接到 Winbio.lib 静态库并包含以下头文件：

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

HRESULT CaptureSampleWithCallback(BOOL bCancel)
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_RAW,            // Raw access
            NULL,                       // Array of biometric unit IDs
            0,                          // Count of biometric unit IDs
            WINBIO_DB_DEFAULT,          // Default database
            &sessionHandle              // [out] Session handle
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Capture a biometric sample asynchronously.
    wprintf_s(L"\n Calling WinBioCaptureSampleWithCallback ");
    hr = WinBioCaptureSampleWithCallback(
            sessionHandle,                  // Open session handle
            WINBIO_NO_PURPOSE_AVAILABLE,    // Intended use of the sample
            WINBIO_DATA_FLAG_RAW,           // Sample format
            CaptureSampleCallback,          // Callback function
            NULL                            // Optional context
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Swipe the sensor ...\n");

    // Cancel the capture process if the bCancel flag is set.
    if (bCancel)
    {
        wprintf_s(L"\n Starting CANCEL timer...");
        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 capture 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)
    {
        WinBioCloseSession(sessionHandle);
        sessionHandle = NULL;
    }

    wprintf_s(L"\n Press any key to exit...");
    _getch();

    return hr;
}

//------------------------------------------------------------------------
// The following function is the callback for WinBioCaptureSampleWithCallback.
// The function filters the response from the biometric subsystem and 
// writes a result to the console window.
//
VOID CALLBACK CaptureSampleCallback(
    __in_opt PVOID CaptureCallbackContext,
    __in HRESULT OperationStatus,
    __in WINBIO_UNIT_ID UnitId,
    __in_bcount(SampleSize) PWINBIO_BIR Sample,
    __in SIZE_T SampleSize,
    __in WINBIO_REJECT_DETAIL RejectDetail
    )
{
    UNREFERENCED_PARAMETER(CaptureCallbackContext);

    wprintf_s(L"\n CaptureSampleCallback executing");
    wprintf_s(L"\n Swipe processed - Unit ID: %d", UnitId);

    if (FAILED(OperationStatus))
    {
        if (OperationStatus == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
         }
        else
        {
            wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
            wprintf_s(L" OperationStatus = 0x%x\n", OperationStatus);
        }
        goto e_Exit;
    }

    wprintf_s(L"\n Captured %d bytes.\n", SampleSize);

e_Exit:

    if (Sample != NULL)
    {
        WinBioFree(Sample);
        Sample = NULL;
    }
}

要求

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

另请参阅

WinBioCaptureSample

通过

WinBioCaptureSampleWithCallback 函数 (winbio.h)

语法

参数

返回值

注解

示例

要求

另请参阅

反馈

其他资源