PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN回调函数 (winbio_adapter.h)

项目
08/27/2023

由传感器适配器实现的 SensorAdapterPushDataToEngine 函数调用，以通知引擎适配器接受原始生物识别样本并提取功能集。功能集可用于匹配或注册。

语法

PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN PibioEngineAcceptSampleDataFn;

HRESULT PibioEngineAcceptSampleDataFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      PWINBIO_BIR SampleBuffer,
  [in]      SIZE_T SampleSize,
  [in]      WINBIO_BIR_PURPOSE Purpose,
  [out]     PWINBIO_REJECT_DETAIL RejectDetail
)
{...}

参数

[in, out] Pipeline

指向与执行操作的生物识别单元关联的 WINBIO_PIPELINE 结构的指针。

[in] SampleBuffer

指向包含要处理的生物识别样本的WINBIO_BIR 结构的指针。

[in] SampleSize

一个SIZE_T值，该值包含 SampleBuffer 参数中返回的 WINBIO_BIR 结构的大小。

[in] Purpose

指定示例的预期用途 的WINBIO_BIR_PURPOSE 位掩码。 WINBIO_BIR_PURPOSE 结构指定使用捕获数据的目的，因此 () 应如何对其进行优化。这可以是以下值的按位 OR ：

WINBIO_PURPOSE_VERIFY
WINBIO_PURPOSE_IDENTIFY
WINBIO_PURPOSE_ENROLL
WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[out] RejectDetail

指向 WINBIO_REJECT_DETAIL 值的指针，该值接收有关处理生物识别样本失败的其他信息。如果操作成功，则此参数设置为零。为指纹样本定义了以下值：

WINBIO_FP_TOO_HIGH
WINBIO_FP_TOO_LOW
WINBIO_FP_TOO_LEFT
WINBIO_FP_TOO_RIGHT
WINBIO_FP_TOO_FAST
WINBIO_FP_TOO_SLOW
WINBIO_FP_POOR_QUALITY
WINBIO_FP_TOO_SKEWED
WINBIO_FP_TOO_SHORT
WINBIO_FP_MERGE_FAILURE

返回值

如果函数成功，则返回S_OK。如果函数失败，则必须返回以下 HRESULT 值之一来指示错误。

返回代码	说明
E_INVALIDARG	SampleSize 参数不能为零。 Purpose 参数必须是参数说明中列出的值的按位 OR。
E_POINTER	Pipeline、SampleBuffer 和 RejectDetail 参数不能为 NULL。
E_OUTOFMEMORY	由于内存不足，操作无法完成。
WINBIO_E_BAD_CAPTURE	无法处理数据以创建所需的功能集。 RejectDetail 包含有关失败的其他信息。

注解

函数返回后，通过调用此函数创建的功能集将保留在生物识别单元管道中。它将替换以前的任何功能集。

SensorAdapterPushDataToEngine 函数的传感器适配器实现应使用以下Winbio_adapter.h) 中定义的包装函数 (调用 EngineAdapterAcceptSampleData：

HRESULT WbioEngineAcceptSampleData(
__inout PWINBIO_PIPELINE Pipeline,
__in PWINBIO_BIR SampleBuffer,
__in SIZE_T SampleSize,
__in WINBIO_BIR_PURPOSE Purpose,
__out PWINBIO_REJECT_DETAIL RejectDetail
);

在 SampleBuffer 参数中传递的WINBIO_BIR结构是传感器适配器的属性。由于传感器适配器控制 WINBIO_BIR 对象的生存期， EngineAdapterAcceptSampleData 函数不得尝试解除分配结构或保存指向它的指针。如果不保存指针，则会阻止引擎适配器的其他部分在 EngineAdapterAcceptSampleData 函数返回后尝试使用 WINBIO_BIR 结构。

如果 WINBIO_BIR 结构的 StandardDataBlock 成员的 Offset 字段大于零 (指示 BIR 包含标准数据格式的生物识别样本) ，则必须按如下所示设置 HeaderBlock 成员的 BiometricDataFormat 字段：

“ 所有者” 字段必须 WINBIO_ ANSI_381_FORMAT_OWNER。
“ 类型” 字段必须 WINBIO_ANSI_381_FORMAT_TYPE。

这是 Windows 生物识别框架支持的唯一标准数据格式。

Windows 生物识别框架还假定 HeaderBlock 成员 (WINBIO_BIR_HEADER 结构) 包含传感器适配器用于捕获样本 的 DataFlags 和 Purpose 值。

处理指纹样本并拒绝引擎适配器中的不良轻扫的指纹传感器还应使用 有效值进行WINBIO_BIR_PURPOSE。

示例

以下伪代码显示了此函数的一种可能实现。该示例不编译。必须根据自己的目的调整它。

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterAcceptSampleData
//
// Purpose:
//      Notifies the engine adapter to accept a raw biometric sample and 
//      extract a feature set.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation. 
//      SampleBuffer    - Contains the biometric sample to be processed.
//      SampleSize      - Size of the structure returned in the SampleBuffer 
//                        parameter.
//      Purpose         - Specifies the intended use of the sample.
//      RejectDetail    - Receives additional information about the failure, 
//                        if any, to process a biometric sample.
//
static HRESULT
WINAPI
EngineAdapterAcceptSampleData(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_BIR SampleBuffer,
    __in SIZE_T SampleSize,
    __in WINBIO_BIR_PURPOSE Purpose,
    __out PWINBIO_REJECT_DETAIL RejectDetail
    )
{
    HRESULT hr = S_OK;
    PUCHAR featureSet = NULL;

    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline)     ||
        !ARGUMENT_PRESENT(SampleBuffer) ||
        !ARGUMENT_PRESENT(RejectDetail))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Retrieve the context from the pipeline.
    PWINBIO_ENGINE_CONTEXT context = 
           (PWINBIO_ENGINE_CONTEXT)Pipeline->EngineContext;

    // Verify that input arguments are valid.
    if (SampleSize == 0 ||
        Purpose == WINBIO_NO_PURPOSE_AVAILABLE)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // Release any feature set currently attached to the pipeline before
    // creating a new feature set.
    if (context->FeatureSet != NULL)
    {
        _AdapterRelease(context->FeatureSet);
        context->FeatureSet = NULL;
        context->FeatureSetSize = 0;
    }

    // An actual engine adapter would here process the contents of the sample 
    // buffer, generate a feature set suitable for the purpose(s) specified 
    // by the Purpose parameter, and attach the feature set to the pipeline. 
    // The following trivial example, however, creates a feature set simply
    // by making an exact copy of the raw sample.
    // If the sample data cannot be processed, return an HRESULT error code
    // of WINBIO_E_BAD_CAPTURE and set extended error information in the 
    // RejectDetail parameter.
    featureSet = (PUCHAR)_AdapterAlloc(SampleSize);
    if (featureSet == NULL)
    {
        hr = E_OUTOFMEMORY;
        goto cleanup;
    }
    RtlCopyMemory(featureSet, SampleBuffer, SampleSize);
    context->FeatureSet = featureSet;
    featureSet = NULL;
    context->FeatureSetSize = SampleSize;

cleanup:

    if (FAILED(hr))
    {
        if (featureSet != NULL)
        {
            _AdapterRelease(featureSet);
        }
    }

    return hr;
}

要求

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

另请参阅

EngineAdapterExportEngineData

插件函数

通过

PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN回调函数 (winbio_adapter.h)

语法

参数

返回值

注解

示例

要求

另请参阅

反馈

其他资源