Share via

PIBIO_ENGINE_EXPORT_ENGINE_DATA_FN回调函数 (winbio_adapter.h)

  • 项目

由 Windows 生物识别框架调用，以从格式化为标准 WINBIO_BIR 结构的引擎中检索最近处理的功能集或模板的副本。

语法

PIBIO_ENGINE_EXPORT_ENGINE_DATA_FN PibioEngineExportEngineDataFn;

HRESULT PibioEngineExportEngineDataFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      WINBIO_BIR_DATA_FLAGS Flags,
  [out]     PWINBIO_BIR *SampleBuffer,
  [out]     PSIZE_T SampleSize
)
{...}

参数

[in, out] Pipeline

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

[in] Flags

一个 值，该值指定引擎返回 的 WINBIO_BIR 结构的属性。 这可以是以下安全和处理级别标志的按位 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_DATA_FLAG_INTERMEDIATE 数据不是原始数据，但尚未完全处理。

  • WINBIO_DATA_FLAG_PROCESSED 数据已处理。

[out] SampleBuffer

接收指向包含功能集或模板 的WINBIO_BIR 结构的指针的变量的地址。

[out] SampleSize

指向变量的指针，该变量包含 SampleBuffer 参数中返回的WINBIO_BIR结构的大小（以字节为单位）。

返回值

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

返回代码 说明
E_INVALIDARG
 引擎适配器不支持标志参数指定的 标志 组合。
E_OUTOFMEMORY
 没有足够的内存可用于创建 WINBIO_BIR 结构。
E_POINTER
 强制指针参数为 NULL。
WINBIO_E_INVALID_DEVICE_STATE
 管道不包含 Flags 参数所需的数据类型。
E_NOTIMPL
 目前未实现此方法。

注解

必须使用 HeapAlloc 函数从进程堆分配要在 SampleBuffer 参数中返回的缓冲区。 创建缓冲区后，它将成为 Windows 生物识别框架的 属性。 由于框架在完成使用此内存后会解除分配此内存，因此此函数的实现不得尝试解除分配缓冲区或保存指向它的指针。 通过不保存指针，可以阻止引擎适配器的其他部分在此函数返回后尝试使用该缓冲区。

示例

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterExportEngineData
//
// Purpose:
//      Retrieves a copy of the most recently processed feature set or template.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation
//      Flags           - Security and processing level flags
//      SampleBuffer    - Contains the feature set or template
//      SampleSize      - Size, in bytes, of the structure returned in the 
//                        SampleBuffer parameter.
//
static HRESULT
WINAPI
EngineAdapterExportEngineData(
    __inout PWINBIO_PIPELINE Pipeline,
    __in WINBIO_BIR_DATA_FLAGS Flags,
    __out PWINBIO_BIR *SampleBuffer,
    __out PSIZE_T SampleSize
    )
{
    HRESULT hr = S_OK;
    PWINBIO_BIR birAddress = NULL;
    SIZE_T birSize = 0;

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

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

    // At least one processing level flag must be set. Your adapter can also
    // place additional restrictions on supported export formats.
    if (Flags & (WINBIO_DATA_FLAG_RAW | 
                 WINBIO_DATA_FLAG_INTERMEDIATE | 
                 WINBIO_DATA_FLAG_PROCESSED) == 0)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // You must implement the _CreateBirFromAdapterData function to extract
    // data from the engine context and create a new WINBIO_BIR structure. The
    // function passes ownership of the new biometric information record (BIR)
    // to the EngineAdapterExportEngineData routine which then passes the BIR
    // to the caller.
    hr = _CreateBirFromAdapterData( context, Flags, &birAddress, &birSize);
    if (SUCCEEDED(hr))
    {
        *SampleBuffer = birAddress;
        *SampleSize = birSize;
    }

cleanup:

    return hr;
}

要求

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

另请参阅

EngineAdapterAcceptSampleData

插件函数