WinBioCaptureSampleWithCallback 函数 （winbio.h）

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

Syntax

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

在准备好用于标记“用途</标记>”<参数指定的>用途后返回该示例。

[in] CaptureCallback

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

[in, optional] CaptureCallbackContext

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

返回值

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

注解

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;
    }
}

要求

另请参阅

WinBioCaptureSample