SensorAdapterAttach function

Called by the Windows Biometric Framework when a sensor adapter is added to the processing pipeline of the biometric unit. The purpose of this function is to perform any initialization required for later biometric operations.


HRESULT WINAPI SensorAdapterAttach(
  _Inout_ PWINBIO_PIPELINE Pipeline


Pipeline [in, out]

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 codeDescription

The Pipeline argument cannot be NULL.


The operation could not be completed because of insufficient memory.


The SensorContext member of the WINBIO_PIPELINE structure pointed to by the Pipeline argument is not NULL.



This function is called before the engine and storage adapters have been initialized for the biometric unit. Therefore, this function must not call any functions referenced by the WINBIO_ENGINE_INTERFACE or the WINBIO_STORAGE_INTERFACE structure 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 before this method is called, your implementation of SensorAdapterAttach can use the handle to access the sensor device if necessary.

When implementing this function, you must allocate and manage any resources required by the adapter and attach these to the biometric unit pipeline. To do this, allocate a private WINBIO_SENSOR_CONTEXT structure on the heap, initialize it, and set its address in the SensorContext member of the pipeline object.

If there is an error during the creation and initialization of engine adapter resources used by this function, you must perform any required cleanup before returning.

If the SensorContext field is not NULL when this function is called, the pipeline was not properly reset by a prior call to SensorAdapterDetach and you must return WINBIO_E_INVALID_DEVICE_STATE to notify the Windows Biometric Framework of the problem.


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

// SensorAdapterAttach
// Purpose:
//      Performs any initialization required for later biometric operations.
// Parameters:
//      Pipeline -  Pointer to a WINBIO_PIPELINE structure associated with 
//                  the biometric unit performing the operation.
static HRESULT
    __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;

    // Validate the current sensor state.
    if (Pipeline->SensorContext != NULL)
        goto cleanup;

    // Use a custom function (_AdapterAlloc) to allocate memory for the 
    // sensor adapter context.
    newContext = (PWINBIO_SENSOR_CONTEXT)_AdapterAlloc(sizeof(WINBIO_SENSOR_CONTEXT));
    if (newContext == NULL)
        hr = E_OUTOFMEMORY;
        goto cleanup;

    // Create a manual reset event to monitor overlapped I/O.
    newContext->Overlapped.hEvent = CreateEvent(NULL, TRUE, FALSE, NULL);
    if (newContext->Overlapped.hEvent == NULL)
        hr = E_OUTOFMEMORY;
        goto cleanup;

    // Initialize any required context fields. This example assumes that your
    // sensor context points to a capture buffer and an attributes buffer.
    newContext->CaptureBuffer = NULL;
    newContext->CaptureBufferSize = 0;

    newContext->AttributesBuffer = NULL;
    newContext->AttributesBufferSize = sizeof (WINBIO_SENSOR_ATTRIBUTES);

    // Transfer ownership of the new sensor context structure to the 
    // pipeline.
    Pipeline->SensorContext = newContext;
    newContext = NULL;


    if (FAILED(hr) && newContext != NULL)
        CloseHandle( newContext->Overlapped.hEvent;
        _AdapterRelease( newContext );
        newContext = NULL;
    return hr;


Minimum supported client

Windows 7 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]


Winbio_adapter.h (include Winbio_adapter.h)

See also

Plug-in Functions