PIBIO_STORAGE_CLEAR_CONTEXT_FN callback function (winbio_adapter.h)

Article
02/22/2024

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_STORAGE_CLEAR_CONTEXT_FN PibioStorageClearContextFn;

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

Parameters

[in, out] Pipeline

Pointer to the 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.
WINBIO_E_INVALID_DEVICE_STATE	The StorageContext member of the WINBIO_PIPELINE structure pointed to by the Pipeline argument is NULL.

Remarks

The following storage adapter context items should be cleared:

Result set - a collection of records generated by the most-recent database query operation.
Result set cursor - an indicator of the current position within the result set. This is used to iterate through the result set and make individual records available.

Examples

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

/////////////////////////////////////////////////////////////////////////////////////////
//
// StorageAdapterClearContext
//
// Purpose:
//      Prepare the processing pipeline of the biometric unit for a 
//      new operation.
//
// Parameters:
//      Pipeline -  Pointer to a WINBIO_PIPELINE structure associated with 
//                  the biometric unit performing the operation.
//
static HRESULT
WINAPI
StorageAdapterClearContext(
    __inout PWINBIO_PIPELINE Pipeline
    )
{
    HRESULT hr = S_OK;

    // Verify that the Pipeline parameter is not NULL.
    if (!ARGUMENT_PRESENT(Pipeline))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Retrieve the context from the pipeline.
    PWINBIO_STORAGE_CONTEXT storageContext = 
           (PWINBIO_STORAGE_CONTEXT)Pipeline->StorageContext;

    // Verify the pipeline state.
    if (storageContext == NULL)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    // Release data structures attached to the context. The following
    // example code shows how to release structures that will likely 
    // be associated with your adapter context.
    _ResultSetClearContents(&storageContext->ResultSet);
    if (storageContext->RawRecordData != NULL)
    {
        _AdapterRelease(storageContext->RawRecordData);
        storageContext->RawRecordData = NULL;
        storageContext->PayloadBlob = NULL;
    }
    if (storageContext->DecryptedTemplate != NULL)
    {
        SecureZeroMemory(
            storageContext->DecryptedTemplate, 
            storageContext->DecryptedTemplateSize
            );
        _AdapterRelease(storageContext->DecryptedTemplate);
        storageContext->DecryptedTemplate = NULL;
        storageContext->DecryptedTemplateSize = 0;
    }

    // TODO: Release any other allocated data structures attached
    // to the context (not shown).

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)