PIBIO_SENSOR_DETACH_FN callback function (winbio_adapter.h)

Article
10/13/2021

Called by the Windows Biometric Framework immediately before a sensor adapter is removed from the processing pipeline of the biometric unit. The purpose of this function is to release adapter specific resources attached to the pipeline.

Syntax

PIBIO_SENSOR_DETACH_FN PibioSensorDetachFn;

HRESULT PibioSensorDetachFn(
  [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 parameter cannot be NULL.
WINBIO_E_INVALID_DEVICE_STATE	The SensorContext field of the WINBIO_PIPELINE structure cannot be NULL.

Remarks

To prevent memory leaks, your implementation of the SensorAdapterDetach function must release the private WINBIO_SENSOR_CONTEXT structure pointed to by the SensorContext member of the pipeline along with any other resources attached to the sensor context.

If the SensorContext field in the pipeline object is NULL when this function is called, the pipeline was not properly initialized and you must return WINBIO_E_INVALID_DEVICE_STATE to notify the Windows Biometric Framework of the problem.

Before returning S_OK, this function must set the SensorContext field of the WINBIO_PIPELINE structure to NULL.

Because this function is called after the storage and engine adapters have been removed from the pipeline, your implementation of this function must not call any functions referenced by the WINBIO_ENGINE_INTERFACE or WINBIO_STORAGE_INTERFACE structures pointed to by the EngineInterface and StorageInterface members of the pipeline object.

Because the SensorHandle member of the WINBIO_PIPELINE structure will contain a valid handle even after SensorAdapterDetach is called, you can use the handle to access the sensor device if necessary. This function should not close the sensor handle. The Windows biometric Framework will do so after SensorAdapterDetach 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.

//////////////////////////////////////////////////////////////////////////////////////////
//
// SensorAdapterDetach
//
// Purpose:
//      Cancels all pending sensor operations.
//      
// Parameters:
//      Pipeline -  Pointer to a WINBIO_PIPELINE structure associated with 
//                  the biometric unit.
//
static HRESULT
WINAPI
SensorAdapterDetach(
    __inout PWINBIO_PIPELINE Pipeline
    )
{
    PWINBIO_SENSOR_CONTEXT sensorContext = NULL;

    // Verify that the Pipeline parameter is not NULL.
    if (!ARGUMENT_PRESENT(Pipeline))
    {
        hr = E_POINTER;
        goto cleanup;
    }
 
    // Validate the current state of the sensor.
    if (Pipeline->SensorContext == NULL)
    {
        return WINBIO_E_INVALID_DEVICE_STATE;
    }

    // Cancel any pending I/O to the device.
    SensorAdapterCancel(Pipeline);

    // Take ownership of the sensor context from the pipeline.
    sensorContext = (PWINBIO_SENSOR_CONTEXT)Pipeline->SensorContext;
    Pipeline->SensorContext = NULL;

    // Release any structures that remain attached to the context block. 
    // The following example assumes that your sensor adapter context 
    // contains pointers to a capture buffer and an attributes buffer.
    if (sensorContext->CaptureBuffer != NULL)
    {
        // Zero the capture buffer.
        SecureZeroMemory(
            sensorContext->CaptureBuffer,
            sensorContext->CaptureBufferSize);

        // Release the capture buffer.
        _AdapterRelease(sensorContext->CaptureBuffer);
        sensorContext->CaptureBuffer = NULL;
        sensorContext->CaptureBufferSize = 0;
    }

    if (sensorContext->AttributesBuffer != NULL)
    {
        // Zero the attributes buffer.
        SecureZeroMemory(
            sensorContext->AttributesBuffer,
            sensorContext->AttributesBufferSize);

        // Release the attributes buffer.
        _AdapterRelease(sensorContext->AttributesBuffer);
        sensorContext->AttributesBuffer = NULL;
        sensorContext->AttributesBufferSize = 0;
    }

    // Close the overlapped I/O event handle.
    CloseHandle(sensorContext->Overlapped.hEvent);

    // Release the context structure.
    _AdapterRelease(sensorContext);
    sensorContext = NULL;
   
    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)

Share via