EngineAdapterCommitEnrollment function

Called by the Windows Biometric Framework to finalize the enrollment object, convert it to a template, and save the template in the database.

Syntax


HRESULT WINAPI EngineAdapterCommitEnrollment(
  _Inout_  PWINBIO_PIPELINE         Pipeline,
  _In_     PWINBIO_IDENTITY         Identity,
  _In_     WINBIO_BIOMETRIC_SUBTYPE SubFactor,
  _In_opt_ PUCHAR                   PayloadBlob,
  _In_     SIZE_T                   PayloadBlobSize
);

Parameters

Pipeline [in, out]

Pointer to a WINBIO_PIPELINE structure associated with the biometric unit performing the operation.

Identity [in]

Pointer to a WINBIO_IDENTITY structure that contains the GUID or SID of the template to be stored in the database.

SubFactor [in]

A WINBIO_BIOMETRIC_SUBTYPE value that specifies the sub-factor associated with the template to be stored in the database.

PayloadBlob [in, optional]

An optional pointer to an array of bytes that contain a verification signature generated by the Windows Biometric Framework.

PayloadBlobSize [in]

The size, in bytes, of the character array pointed to by the PayloadBlob parameter. This value must be zero if the PayloadBlob parameter is NULL.

Return value

If the function succeeds, it returns S_OK. If the function fails, it must return one of the following HRESULT values or any value returned by the storage adapter.

Return codeDescription
E_POINTER

A mandatory pointer argument is NULL.

E_INVALIDARG

The value specified by the Identity parameter or the SubFactor parameter is not valid.

WINBIO_E_DUPLICATE_ENROLLMENT

The template specified by the Identity and SubFactor parameters is already saved in the database.

WINBIO_E_INVALID_DEVICE_STATE

There is no template attached to the pipeline.

 

Remarks

If this function succeeds, it should flush the enrollment template from the pipeline. The result of this action should be equivalent to calling EngineAdapterClearContext.

If this function fails, it should not change the state of the engine context. In particular, if there is a completed template attached to the pipeline, it should be possible to call this function again (after reasons for any failure have been addressed) to commit the template to the database.

Engine adapters that support pre-boot authentication must commit the enrollment not only to the storage adapter attached to the pipeline, but also to the pre-boot storage area. The details of how this is to be accomplished are left to the vendor.

Important  

Do not attempt to validate the value supplied for the SubFactor parameter. The Windows Biometrics Service will validate the supplied value before passing it through to your implementation. If the value is WINBIO_SUBTYPE_NO_INFORMATION or WINBIO_SUBTYPE_ANY, then validate where appropriate.

 

Examples

The following pseudocode shows one possible implementation of this function. The example does not compile. You must adapt it to suit your purpose.


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


Requirements

Minimum supported client

Windows 7 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]

Header

Winbio_adapter.h (include Winbio_adapter.h)

See also

EngineAdapterClearContext
Plug-in Functions

 

 

Show: