PIBIO_ENGINE_DETACH_FN

エンジン アダプターがバイオメトリック ユニットの処理パイプラインから削除される直前に、Windows Biometric Framework によって呼び出されます。この関数の目的は、パイプラインにアタッチされているアダプター固有のリソースを解放することです。

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

メモリ リークを防ぐため、EngineAdapterDetach 関数の実装では、パイプラインの EngineContext メンバーが指すプライベートな WINBIO_ENGINE_CONTEXT 構造体と、エンジン コンテキストにアタッチされているその他のリソースを解放する必要があります。

この関数が呼び出されたときにパイプライン オブジェクトの EngineContext フィールドが NULL である場合、パイプラインは適切に初期化されていません。その場合は、この問題を Windows Biometric Framework に通知するために WINBIO_E_INVALID_DEVICE_STATE を返す必要があります。

S_OK を返す前に、EngineAdapterDetach 関数は WINBIO_PIPELINE 構造体の EngineContext フィールドを NULL に、EngineHandle フィールドを INVALID_HANDLE_VALUE に設定する必要があります。

この関数は、ストレージ アダプターがパイプラインから削除された後に呼び出されます。そのため、この関数は、パイプライン オブジェクトの StorageInterface メンバーが指す WINBIO_STORAGE_INTERFACE 構造体によって参照される関数を呼び出してはなりません。

例

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterDetach
//
// Purpose:
//      パイプラインにアタッチされているアダプター固有のリソースを解放します。
//      
// Parameters:
//      Pipeline -  バイオメトリック ユニットに関連付けられた WINBIO_PIPELINE
//                  構造体へのポインター。
//
static HRESULT
WINAPI
EngineAdapterDetach(
    __inout PWINBIO_PIPELINE Pipeline
    )
{
    PWINBIO_ENGINE_CONTEXT context = NULL;

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

    // パイプラインからコンテキストを取得し、ローカル変数に
    // 代入します。
    context = (PWINBIO_ENGINE_CONTEXT)Pipeline->EngineContext;
    if (context == NULL)
    {
        goto cleanup;
    }

    // パイプライン上のコンテキストを NULL に設定します。
    Pipeline->EngineContext = NULL;

    // アダプターがソフトウェアベースのテンプレート ハッシュをサポートしており、
    // 初期化時に Cryptography Next Generation (CNG) ハッシュ オブジェクトの
    // ハンドルを開いている場合は、次のカスタム関数を実装して CNG リソースを
    // 解放します。
    _AdapterCleanupCrypto(context);

    // コンテキスト ブロックにアタッチされたままの構造体を解放するために、
    // 1 つ以上のカスタム ルーチンを実装します。これらの構造体には、最新の
    // フィーチャ セット、現在の登録テンプレート、その他の独自定義の
    // オブジェクトなどが含まれます。
    if (context->FeatureSet != NULL)
    {
        _AdapterRelease(context->FeatureSet);
        context->FeatureSet = NULL;
        context->FeatureSetSize = 0;
    }

    if (context->Enrollment.Template != NULL)
    {
        _AdapterRelease(context->Enrollment.Template);
        context->Enrollment.Template = NULL;
        context->Enrollment.TemplateSize = 0;
        context->Enrollment.SampleCount = 0;
    }

    if (context->SomePointerField != NULL)
    {
        _AdapterRelease(context->SomePointerField);
        context->SomePointerField = NULL;
    }

    // コンテキスト ブロックを解放します。
    _AdapterRelease(context);

cleanup:

    return S_OK;
}