通过

PIBIO_ENGINE_COMMIT_ENROLLMENT_FN回调函数 (winbio_adapter.h)

  • 项目

由 Windows 生物识别框架调用以完成注册对象，将其转换为模板，并将模板保存在数据库中。

语法

PIBIO_ENGINE_COMMIT_ENROLLMENT_FN PibioEngineCommitEnrollmentFn;

HRESULT PibioEngineCommitEnrollmentFn(
  [in, out]      PWINBIO_PIPELINE Pipeline,
  [in]           PWINBIO_IDENTITY Identity,
  [in]           WINBIO_BIOMETRIC_SUBTYPE SubFactor,
  [in, optional] PUCHAR PayloadBlob,
  [in]           SIZE_T PayloadBlobSize
)
{...}

参数

[in, out] Pipeline

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

[in] Identity

指向 WINBIO_IDENTITY 结构的指针，该结构包含要存储在数据库中的模板的 GUID 或 SID。

[in] SubFactor

一个WINBIO_BIOMETRIC_SUBTYPE值，该值指定与要存储在数据库中的模板关联的子因子。

[in, optional] PayloadBlob

指向包含 Windows 生物识别框架生成的验证签名的字节数组的可选指针。

[in] PayloadBlobSize

PayloadBlob 参数指向的字符数组的大小（以字节为单位）。 如果 PayloadBlob 参数为 NULL，则此值必须为 零。

返回值

如果函数成功，则返回S_OK。 如果函数失败，它必须返回以下 HRESULT 值之一或存储适配器返回的任何值。

返回代码 说明
E_POINTER
 强制指针参数为 NULL。
E_INVALIDARG
 Identity 参数或 SubFactor 参数指定的值无效。
WINBIO_E_DUPLICATE_ENROLLMENT
 Identity 和 SubFactor 参数指定的模板已保存在数据库中。
WINBIO_E_INVALID_DEVICE_STATE
 管道中没有附加的模板。

注解

如果此函数成功，它应从管道中刷新注册模板。 此操作的结果应等效于调用 EngineAdapterClearContext。

如果此函数失败，则不应更改引擎上下文的状态。 具体而言，如果管道附加了已完成的模板，则应可以在 (解决任何失败原因后再次调用此函数，) 将模板提交到数据库。

支持预启动身份验证的引擎适配器不仅必须将注册提交到附加到管道的存储适配器，还必须提交到预启动存储区域。 如何完成此操作的详细信息留给供应商。

重要说明  

请勿尝试验证为 SubFactor 参数提供的值。 Windows 生物识别服务会在将所提供的值传递给实现之前对其进行验证。 如果值为 WINBIO_SUBTYPE_NO_INFORMATION 或 WINBIO_SUBTYPE_ANY，请在适当位置进行验证。

 

示例

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterCommitEnrollment
//
// Purpose:
//      Finalizes the enrollment object, converts it to a template, and saves 
//      the template in the database.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation
//      Identity        - GUID or SID of the template to be stored in the 
//                        database
//      SubFactor       - Sub-factor associated with the template to be stored
//                        in the database
//      PayloadBlob     - Optional pointer to an array of bytes that contain a 
//                        verification signature generated by the Windows Biometric
//                        Framework
//      PayloadBlobSize - Size, in bytes, of the character array pointed to by 
//                        the PayloadBlob parameter
//

static HRESULT
WINAPI
EngineAdapterCommitEnrollment(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_IDENTITY Identity,
    __in WINBIO_BIOMETRIC_SUBTYPE SubFactor,
    __in PUCHAR PayloadBlob,
    __in SIZE_T PayloadBlobSize
    )
{
    HRESULT hr = S_OK;
    DWORD indexVector[NUMBER_OF_TEMPLATE_BINS] = {0};
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    WINBIO_STORAGE_RECORD newTemplate = {0};

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

    if (ARGUMENT_PRESENT(PayloadBlob) && PayloadBlobSize == 0)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }
    
    if (!ARGUMENT_PRESENT(PayloadBlob) && PayloadBlobSize > 0)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // TODO: Verify that the SubFactor and Identity arguments are valid.

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

    // Return if an enrollment is not in progress. This example assumes that 
    // an enrollment object is part of your engine context structure.
    if (context->Enrollment.InProgress != TRUE)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    // If your adapter supports index vectors to place templates into buckets,
    // call a custom function (_AdapterCreateIndexVector) to create an index 
    // vector from the template data in the enrollment object.
    hr = _AdapterCreateIndexVector(
                context, 
                context->Enrollment.Template, 
                context->Enrollment.TemplateSize,
                indexVector, 
                NUMBER_OF_TEMPLATE_BINS, 
                &rejectDetail
                );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    newTemplate.Identity = Identity;
    newTemplate.SubFactor = SubFactor;
    newTemplate.IndexVector = indexVector;
    newTemplate.IndexElementCount = NUMBER_OF_TEMPLATE_BINS;
    newTemplate.TemplateBlob = context->Enrollment.Template;
    newTemplate.TemplateBlobSize = context->Enrollment.TemplateSize;
    newTemplate.PayloadBlob = PayloadBlob;
    newTemplate.PayloadBlobSize = PayloadBlobSize;

    hr = WbioStorageAddRecord(
                Pipeline,
                &newTemplate
                );

    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Call a custom function (_AdapterDestroyEnrollmentTemplate) to release
    // any resources held by the enrollment object.
    _AdapterDestroyEnrollmentTemplate(
        context,
        &context->Enrollment
        );

    // Specify that the enrollment process has been completed.
    context->Enrollment.InProgress = FALSE;

cleanup:

    return hr;
}

要求

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

另请参阅

EngineAdapterClearContext

插件函数