PIBIO_ENGINE_EXPORT_ENGINE_DATA_FN callback function (winbio_adapter.h)

Article
10/21/2021

Called by the Windows Biometric Framework to retrieve a copy of the most recently processed feature set or template from the engine formatted as a standard WINBIO_BIR structure.

Syntax

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
)
{...}

Parameters

[in, out] Pipeline

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

[in] Flags

A value that specifies the properties of the WINBIO_BIR structure returned by the engine. This can be a bitwise OR of the following security and processing level flags:

WINBIO_DATA_FLAG_PRIVACY

The data is encrypted.

WINBIO_DATA_FLAG_INTEGRITY The data is digitally signed or protected by a message authentication code (MAC).
WINBIO_DATA_FLAG_SIGNED If this flag and the WINBIO_DATA_FLAG_INTEGRITY flag are set, the data is signed. If this flag is not set but the WINBIO_DATA_FLAG_INTEGRITY flag is set, a MAC is computed.
WINBIO_DATA_FLAG_RAW The data is in the format with which it was captured.
WINBIO_DATA_FLAG_INTERMEDIATE The data is not raw but has not been completely processed.
WINBIO_DATA_FLAG_PROCESSED The data has been processed.

[out] SampleBuffer

Address of a variable that receives a pointer to a WINBIO_BIR structure that contains the feature set or template.

[out] SampleSize

Pointer to a variable that contains the size, in bytes, of the WINBIO_BIR structure returned in the SampleBuffer parameter.

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 engine adapter does not support the combination of flags specified by the Flags parameter.
E_OUTOFMEMORY	There is not enough memory available to create the WINBIO_BIR structure.
E_POINTER	A mandatory pointer parameter is NULL.
WINBIO_E_INVALID_DEVICE_STATE	The pipeline does not contain the type of data required by the Flags parameter.
E_NOTIMPL	This method is not currently implemented.

Remarks

You must allocate the buffer to be returned in the SampleBuffer parameter from the process heap by using the HeapAlloc function. After the buffer is created, it becomes the property of the Windows Biometric Framework. Because the Framework deallocates this memory when finished using it, your implementation of this function must not attempt to deallocate the buffer or save a pointer to it. By not saving the pointer, you prevent other parts of the engine adapter from attempting to use the buffer after this function returns.

Examples

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

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

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)