PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN callback function (winbio_adapter.h)

Article
10/13/2021

Called by the SensorAdapterPushDataToEngine function implemented by the sensor adapter to notify the engine adapter to accept a raw biometric sample and extract a feature set. The feature set can be used for matching or enrollment.

Syntax

PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN PibioEngineAcceptSampleDataFn;

HRESULT PibioEngineAcceptSampleDataFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      PWINBIO_BIR SampleBuffer,
  [in]      SIZE_T SampleSize,
  [in]      WINBIO_BIR_PURPOSE Purpose,
  [out]     PWINBIO_REJECT_DETAIL RejectDetail
)
{...}

Parameters

[in, out] Pipeline

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

[in] SampleBuffer

Pointer to a WINBIO_BIR structure that contains the biometric sample to be processed.

[in] SampleSize

A SIZE_T value that contains the size of the WINBIO_BIR structure returned in the SampleBuffer parameter.

[in] Purpose

A WINBIO_BIR_PURPOSE bitmask that specifies the intended use of the sample. The WINBIO_BIR_PURPOSE structure specifies the purpose for which capture data is to be used, and (as a result) how it should be optimized. This can be a bitwise OR of the following values:

WINBIO_PURPOSE_VERIFY
WINBIO_PURPOSE_IDENTIFY
WINBIO_PURPOSE_ENROLL
WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[out] RejectDetail

A pointer to a WINBIO_REJECT_DETAIL value that receives additional information about the failure to process a biometric sample. If the operation succeeded, this parameter is set to zero. The following values are defined for fingerprint samples:

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

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_INVALIDARG	The SampleSize argument cannot be zero. The Purpose argument must be a bitwise OR of the values listed in the parameter description.
E_POINTER	The Pipeline, SampleBuffer, and RejectDetail arguments cannot be NULL.
E_OUTOFMEMORY	The operation could not be completed because of insufficient memory.
WINBIO_E_BAD_CAPTURE	The data could not be processed to create the required feature set. The RejectDetail contains additional information about the failure.

Remarks

The feature set created by calling this function is retained in the biometric unit pipeline after the function returns. It replaces any previous feature set.

The sensor adapter implementation of the SensorAdapterPushDataToEngine function should use the following wrapper function (defined in Winbio_adapter.h) to call EngineAdapterAcceptSampleData:

HRESULT WbioEngineAcceptSampleData(
__inout PWINBIO_PIPELINE Pipeline,
__in PWINBIO_BIR SampleBuffer,
__in SIZE_T SampleSize,
__in WINBIO_BIR_PURPOSE Purpose,
__out PWINBIO_REJECT_DETAIL RejectDetail
);

The WINBIO_BIR structure that is passed in the SampleBuffer parameter is the property of the sensor adapter. Because the sensor adapter controls the lifetime of the WINBIO_BIR object, the EngineAdapterAcceptSampleData function must not attempt to deallocate the structure or save a pointer to it. By not saving the pointer, you prevent other parts of the engine adapter from attempting to use the WINBIO_BIR structure after the EngineAdapterAcceptSampleData function returns.

If the Offset field of the StandardDataBlock member of the WINBIO_BIR structure is greater than zero (indicating that the BIR contains a biometric sample in the standard data format), the BiometricDataFormat field of the HeaderBlock member must be set as follows:

The Owner field must be WINBIO_ ANSI_381_FORMAT_OWNER.
The Type field must be WINBIO_ANSI_381_FORMAT_TYPE.

This is the only standard data format supported by the Windows Biometric Framework.

The Windows Biometric Framework also assumes that the HeaderBlock member (a WINBIO_BIR_HEADER structure) contains the DataFlags and Purpose values used by the sensor adapter to capture the sample.

Fingerprint sensors processing fingerprint samples and rejecting bad swipes in the Engine Adapter should also use valid values for WINBIO_BIR_PURPOSE.

Examples

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterAcceptSampleData
//
// Purpose:
//      Notifies the engine adapter to accept a raw biometric sample and 
//      extract a feature set.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation. 
//      SampleBuffer    - Contains the biometric sample to be processed.
//      SampleSize      - Size of the structure returned in the SampleBuffer 
//                        parameter.
//      Purpose         - Specifies the intended use of the sample.
//      RejectDetail    - Receives additional information about the failure, 
//                        if any, to process a biometric sample.
//
static HRESULT
WINAPI
EngineAdapterAcceptSampleData(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_BIR SampleBuffer,
    __in SIZE_T SampleSize,
    __in WINBIO_BIR_PURPOSE Purpose,
    __out PWINBIO_REJECT_DETAIL RejectDetail
    )
{
    HRESULT hr = S_OK;
    PUCHAR featureSet = NULL;

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

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

    // Verify that input arguments are valid.
    if (SampleSize == 0 ||
        Purpose == WINBIO_NO_PURPOSE_AVAILABLE)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // Release any feature set currently attached to the pipeline before
    // creating a new feature set.
    if (context->FeatureSet != NULL)
    {
        _AdapterRelease(context->FeatureSet);
        context->FeatureSet = NULL;
        context->FeatureSetSize = 0;
    }

    // An actual engine adapter would here process the contents of the sample 
    // buffer, generate a feature set suitable for the purpose(s) specified 
    // by the Purpose parameter, and attach the feature set to the pipeline. 
    // The following trivial example, however, creates a feature set simply
    // by making an exact copy of the raw sample.
    // If the sample data cannot be processed, return an HRESULT error code
    // of WINBIO_E_BAD_CAPTURE and set extended error information in the 
    // RejectDetail parameter.
    featureSet = (PUCHAR)_AdapterAlloc(SampleSize);
    if (featureSet == NULL)
    {
        hr = E_OUTOFMEMORY;
        goto cleanup;
    }
    RtlCopyMemory(featureSet, SampleBuffer, SampleSize);
    context->FeatureSet = featureSet;
    featureSet = NULL;
    context->FeatureSetSize = SampleSize;

cleanup:

    if (FAILED(hr))
    {
        if (featureSet != NULL)
        {
            _AdapterRelease(featureSet);
        }
    }

    return hr;
}

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)