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.

Syntax


HRESULT WINAPI SensorAdapterAttach(
  _Inout_  PWINBIO_PIPELINE Pipeline
);

Parameters

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
E_POINTER

The Pipeline argument cannot be NULL.

E_OUTOFMEMORY

The operation could not be completed because of insufficient memory.

WINBIO_E_INVALID_DEVICE_STATE

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

 

Remarks

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.

Examples

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
WINAPI
SensorAdapterAttach(
    __inout PWINBIO_PIPELINE Pipeline
    )
{
    HRESULT hr = S_OK;
    PWINBIO_SENSOR_CONTEXT newContext = NULL;

    // 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)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        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;

cleanup:

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


Requirements

Minimum supported client

Windows 7 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]

Header

Winbio_adapter.h (include Winbio_adapter.h)

See also

Plug-in Functions
EngineAdapterAttach
SensorAdapterDetach
StorageAdapterAttach
WINBIO_PIPELINE

 

 

Community Additions

ADD
Show:
© 2014 Microsoft