PIBIO_SENSOR_PUSH_DATA_TO_ENGINE_FN回调函数 (winbio_adapter.h)

由 Windows 生物识别框架调用，使示例缓冲区的当前内容可供引擎适配器使用。

语法

PIBIO_SENSOR_PUSH_DATA_TO_ENGINE_FN PibioSensorPushDataToEngineFn;

HRESULT PibioSensorPushDataToEngineFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      WINBIO_BIR_PURPOSE Purpose,
  [in]      WINBIO_BIR_DATA_FLAGS Flags,
  [out]     PWINBIO_REJECT_DETAIL RejectDetail
)
{...}

参数

[in, out] Pipeline

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

[in] Purpose

一个 值，该值指定将传递给引擎的 WINBIO_BIR 结构的属性。 这可以是以下安全和处理级别标志的按位 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_INTEGRITY 标志，则应对示例进行签名。 如果未设置此标志，但设置了WINBIO_DATA_FLAG_INTEGRITY 标志，则应计算 MAC。

• WINBIO_DATA_FLAG_RAW

示例应以捕获它的格式放置在 WINBIO_BIR 对象中。

[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_POINTER	强制指针参数为 NULL。
WINBIO_E_BAD_CAPTURE	示例数据不适合使用。 如果返回此错误代码，还必须在 RejectDetail 参数中指定一个值，以指示问题的性质。
WINBIO_E_INVALID_DEVICE_STATE	Pipeline 参数指向的 WINBIO_PIPELINE 结构的 SensorContext 成员为 NULL。
WINBIO_E_NO_CAPTURE_DATA	不存在捕获数据。

注解

此函数的实现应将示例缓冲区中包含的原始数据转换为标准 WINBIO_BIR 结构，并使用 EngineAdapterAcceptSampleData 函数将此结构推送到引擎。 执行此操作的正确方法是调用 Winbio_adapter.h 头文件中定义的 WbioEngineAcceptSampleData 帮助程序函数。

如果 EngineAdapterAcceptSampleData 函数返回WINBIO_E_BAD_CAPTURE， 则 SensorAdapterPushDataToEngine 的实现应返回引擎适配器传播的 RejectDetail 值。

传感器适配器保留传递给 EngineAdapterAcceptSampleData 的示例缓冲区的所有权。 传感器适配器负责在 EngineAdapterAcceptSampleData 返回后的某个时间点释放此缓冲区。

示例

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// SensorAdapterPushDataToEngine
//
// Purpose:
//      Makes the current contents of the sample buffer available to the 
//      engine adapter.
//      
// Parameters:
//      Pipeline     -  Pointer to a WINBIO_PIPELINE structure associated with 
//                      the biometric unit.
//      Purpose      -  Specifies the properties of the WINBIO_BIR structure 
//                      that will be passed to the engine.
//      Flags        -  A value that specifies the format of the sample.
//      RejectDetail -  Pointer to a WINBIO_REJECT_DETAIL value that receives 
//                      additional information about the reason the sample
//                      buffer is empty.
//
static HRESULT
WINAPI
SensorAdapterPushDataToEngine(
    __inout PWINBIO_PIPELINE Pipeline,
    __in WINBIO_BIR_PURPOSE Purpose,
    __in WINBIO_BIR_DATA_FLAGS Flags,
    __out PWINBIO_REJECT_DETAIL RejectDetail
    )
{
    HRESULT hr = S_OK;

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

    // Retrieve the context from the pipeline.
    PWINBIO_SENSOR_CONTEXT sensorContext = 
                 (PWINBIO_SENSOR_CONTEXT)Pipeline->SensorContext;

    // Verify the state of the pipeline.
    if (sensorContext == NULL)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    if (sensorContext->CaptureBuffer != NULL &&
        sensorContext->CaptureBufferSize >= sizeof (WINBIO_CAPTURE_DATA) &&
        sensorContext->CaptureBuffer->CaptureData.Size != 0 &&
        sensorContext->CaptureBuffer->SensorStatus == WINBIO_SENSOR_ACCEPT)
    {
        // There is valid capture data in the Pipeline. Call the 
        // WbioEngineAcceptSampleData function to notify the engine adapter, but
        // retain ownership of the buffer in the sensor adapter. 
        // WbioEngineAcceptSampleData is a wrapper function declared in the
        // Winbio_adapter.h header file.
        hr = WbioEngineAcceptSampleData(
                    Pipeline,
                    (PWINBIO_BIR)sensorContext->CaptureBuffer->CaptureData.Data,
                    sensorContext->CaptureBuffer->CaptureData.Size,
                    Purpose,
                    RejectDetail
                    );
    }
    else if (sensorContext->CaptureBuffer != NULL &&
             sensorContext->CaptureBufferSize >= sizeof (WINBIO_CAPTURE_DATA) &&
             sensorContext->CaptureBuffer->WinBioHresult == WINBIO_E_BAD_CAPTURE)
    {
        // The most recent capture was not acceptable.  Do not attempt to push 
        // the sample to the engine. Instead, simply return the reject detail
        // information generated by the previous capture.
        hr = sensorContext->CaptureBuffer->WinBioHresult;
        *RejectDetail = sensorContext->CaptureBuffer->RejectDetail;
    }
    else
    {
        hr = WINBIO_E_NO_CAPTURE_DATA;
    }

    return hr;
}

要求

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

另请参阅

插件函数