PIBIO_STORAGE_ATTACH_FN

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

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

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

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

同様に、この関数が呼び出されたときに StorageHandle フィールドに INVALID_HANDLE_VALUE が格納されていない場合も、WINBIO_E_INVALID_DEVICE_STATE を返す必要があります。

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

例

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

/////////////////////////////////////////////////////////////////////////////////////////
//
// StorageAdapterAttach
//
// 目的:
//      後続の生体認証操作に必要な初期化を行います。
//
// パラメーター:
//      Pipeline -  操作を実行する生体認証ユニットに関連付けられた
//                  WINBIO_PIPELINE 構造体へのポインター。
//
static HRESULT
WINAPI
StorageAdapterAttach(
    __inout PWINBIO_PIPELINE Pipeline
    )
{
    HRESULT hr = S_OK;
    PWINBIO_STORAGE_CONTEXT newContext = NULL;

    // Pipeline パラメーターが NULL でないことを確認します。
    if (!ARGUMENT_PRESENT(Pipeline))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    if (Pipeline->StorageContext != NULL ||
        Pipeline->StorageHandle != INVALID_HANDLE_VALUE)
    { 
        // パイプラインの状態が有効ではありません。パイプラインが既にストレージ
        // コンテキストまたは有効なストレージハンドルを保持している場合、この関数が
        // 呼び出されることはありません。
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    // カスタム関数 (_AdapterAlloc) を呼び出して、センサーアダプターのコンテキストを
    // 保持するメモリを割り当てます。
    newContext = (PWINBIO_STORAGE_CONTEXT)_AdapterAlloc(sizeof(WINBIO_STORAGE_CONTEXT));
    if (newContext == NULL)
    {
        hr = E_OUTOFMEMORY;
        goto cleanup;
    }

    // カスタム関数を呼び出して、次のクエリ操作で使用する結果セットを初期化します。
    // 初期化では通常、前回のクエリの結果セットをクリアし、セットを空としてマークし、
    // 結果セットのカーソルを既知の状態に設定する必要があります。
    // 結果セットはストレージコンテキストに関連付けられ、あるストレージアダプターの
    // 呼び出しから次の呼び出しへと保持されます。
    hr = _ResultSetInitialize(&newContext->ResultSet);
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // TODO: 必要なその他のコンテキストフィールドを初期化します (ここでは省略)。


    // 初期化が正常に完了したら、コンテキストを生体認証ユニットの処理パイプラインに
    // 関連付けます。
    Pipeline->StorageContext = newContext;
    newContext = NULL;

cleanup:

    if (FAILED(hr) && newContext != NULL)
    {
        _ResultSetCleanup(&newContext->ResultSet);
        _AdapterRelease( newContext );
        newContext = NULL;
    }
    return hr;
}