PIBIO_SENSOR_ATTACH_FN

生体認証ユニットの処理パイプラインにセンサーアダプターが追加されたときに、Windows Biometric Framework によって呼び出されます。この関数の目的は、以降の生体認証操作に必要な初期化を行うことです。

関数が成功した場合は S_OK を返します。関数が失敗した場合は、エラーを示すために次のいずれかの HRESULT 値を返す必要があります。

この関数は、生体認証ユニットのエンジンアダプターおよびストレージアダプターが初期化される前に呼び出されます。そのため、この関数では、パイプラインオブジェクトの EngineInterface メンバーおよび StorageInterface メンバーが指す WINBIO_ENGINE_INTERFACE 構造体または WINBIO_STORAGE_INTERFACE 構造体から参照される関数を呼び出してはなりません。

このメソッドが呼び出される前に、WINBIO_PIPELINE 構造体の SensorHandle メンバーには有効なハンドルが格納されています。そのため、SensorAdapterAttach の実装では、必要に応じてこのハンドルを使用してセンサーデバイスにアクセスできます。

この関数を実装する際は、アダプターが必要とするリソースを割り当てて管理し、それらを生体認証ユニットのパイプラインに関連付ける必要があります。そのためには、プライベートな WINBIO_SENSOR_CONTEXT 構造体をヒープ上に割り当てて初期化し、そのアドレスをパイプラインオブジェクトの SensorContext メンバーに設定します。

この関数で使用するエンジンアダプターのリソースの作成および初期化中にエラーが発生した場合は、制御を返す前に必要なクリーンアップを実行する必要があります。

この関数が呼び出されたときに SensorContext フィールドが NULL でない場合は、事前の SensorAdapterDetach の呼び出しによってパイプラインが適切にリセットされていないことを意味します。この場合は、問題を Windows Biometric Framework に通知するために WINBIO_E_INVALID_DEVICE_STATE を返す必要があります。

例

次の擬似コードは、この関数の実装例の 1 つを示しています。この例はそのままではコンパイルできません。目的に合わせて適宜変更してください。

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