PIBIO_ENGINE_CLEAR_CONTEXT_FN callback function (winbio_adapter.h)

Article
07/27/2022

Called by the Windows Biometric Framework to prepare the processing pipeline of the biometric unit for a new operation. This function should flush temporary data from the engine context and place the engine adapter into a well-defined initial state.

Syntax

PIBIO_ENGINE_CLEAR_CONTEXT_FN PibioEngineClearContextFn;

HRESULT PibioEngineClearContextFn(
  [in, out] PWINBIO_PIPELINE Pipeline
)
{...}

Parameters

[in, out] Pipeline

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

Return value

If the function succeeds, it returns S_OK. If the function fails, it must return one of the following HRESULT values to indicate the error.

Return code	Description
E_POINTER	The Pipeline argument cannot be NULL.

Remarks

This purpose of this function is to reset the context to the state it was in immediately after a call to the EngineAdapterAttach function. The context is a reusable structure. The EngineAdapterClearContext function reinitializes the context but does not remove it from the pipeline.

Typical examples of the objects in the engine adapter context area that should be cleared include the following.

Object	Description
Feature set	Contains a description of a biometric sample
Enrollment	Tracks the current state of an enrollment transaction.
Template	Biometric template created by the feature set or the enrollment object.
Comparison	Contains the result of a comparison between the template and the feature set.
Index vector	Contains a set of index values associated with the template.

Examples

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterClearContext
//
// Purpose:
//      Prepares the processing pipeline of the biometric unit for a 
//      new operation.
//
// Parameters:
//      Pipeline -  Pointer to a WINBIO_PIPELINE structure associated with 
//                  the biometric unit.
//
static HRESULT
WINAPI
EngineAdapterClearContext(
    __inout PWINBIO_PIPELINE Pipeline
    )
{
    // Verify that the Pipeline parameter is not NULL.
    if (!ARGUMENT_PRESENT(Pipeline))
    {
        hr = E_POINTER;
        goto cleanup;
    }

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

    if (context == NULL)
    {
        goto cleanup;
    }

    // Change the engine adapter state and discard any partially completed
    // operations. Depending on the adapter, this can involve changes to state 
    // variables or actions implemented in hardware. The following example
    // assumes that your engine adapter context contains a ULONG data member 
    // and pointers to a feature set and an enrollment object.

    context->SomeField = 0L;

    if (context->FeatureSet != NULL)
    {
        // Zero the feature set if it contains unencrypted biometric data.
        SecureZeroMemory(
            context->FeatureSet,
            context->FeatureSetSize);

        // Release the feature set.
        _AdapterRelease(context->FeatureSet);
        context->FeatureSet = NULL;
        context->FeatureSetSize = 0;
    }

    if (context->Enrollment.Template != NULL)
    {
        // Zero the template if it contains unencrypted biometric data.
        SecureZeroMemory(
            context->Enrollment.Template,
            context->Enrollment.TemplateSize);

        // Release the template.
        _AdapterRelease(context->Enrollment.Template);
        context->Enrollment.Template = NULL;
        context->Enrollment.TemplateSize = 0;

        // Release other data members attached to the enrollment object.
        context->Enrollment.SampleCount = 0;
        context->Enrollment.InProgress = FALSE;
    }

cleanup:

    return S_OK;
}

Requirements

Requirement	Value
Minimum supported client	Windows 7 [desktop apps only]
Minimum supported server	Windows Server 2008 R2 [desktop apps only]
Target Platform	Windows
Header	winbio_adapter.h (include Winbio_adapter.h)