PIBIO_ENGINE_COMMIT_ENROLLMENT_FN コールバック関数 (winbio_adapter.h)

[アーティクル]
03/03/2024

Windows 生体認証フレームワークによって呼び出され、登録オブジェクトの最終処理、テンプレートへの変換、データベースへのテンプレートの保存が行われます。

構文

PIBIO_ENGINE_COMMIT_ENROLLMENT_FN PibioEngineCommitEnrollmentFn;

HRESULT PibioEngineCommitEnrollmentFn(
  [in, out]      PWINBIO_PIPELINE Pipeline,
  [in]           PWINBIO_IDENTITY Identity,
  [in]           WINBIO_BIOMETRIC_SUBTYPE SubFactor,
  [in, optional] PUCHAR PayloadBlob,
  [in]           SIZE_T PayloadBlobSize
)
{...}

パラメーター

[in, out] Pipeline

操作を実行する生体認証ユニットに関連付けられている WINBIO_PIPELINE 構造体へのポインター。

[in] Identity

データベースに格納するテンプレートの GUID または SID を含む WINBIO_IDENTITY構造体へのポインター。

[in] SubFactor

データベースに格納するテンプレートに関連付けられているサブ要素を指定するWINBIO_BIOMETRIC_SUBTYPE値。

[in, optional] PayloadBlob

Windows 生体認証フレームワークによって生成された検証署名を含むバイト配列への省略可能なポインター。

[in] PayloadBlobSize

PayloadBlob パラメーターが指す文字配列のサイズ (バイト単位)。 PayloadBlob パラメーターが NULL の場合、この値は 0 である必要があります。

戻り値

関数が成功した場合は、S_OK を返します。関数が失敗した場合は、次のいずれかの HRESULT 値、またはストレージアダプターによって返される値を返す必要があります。

リターンコード	説明
E_POINTER	必須のポインター引数は NULL です。
E_INVALIDARG	Identity パラメーターまたは SubFactor パラメーターで指定された値が無効です。
WINBIO_E_DUPLICATE_ENROLLMENT	Identity パラメーターと SubFactor パラメーターで指定されたテンプレートは、既にデータベースに保存されています。
WINBIO_E_INVALID_DEVICE_STATE	パイプラインにアタッチされたテンプレートはありません。

注釈

この関数が成功した場合は、パイプラインから登録テンプレートをフラッシュする必要があります。このアクションの結果は、 EngineAdapterClearContext を呼び出すことと同じになります。

この関数が失敗した場合は、エンジンコンテキストの状態を変更しないでください。特に、完成したテンプレートがパイプラインにアタッチされている場合は、(エラーの理由に対処した後に) この関数を再度呼び出して、テンプレートをデータベースにコミットできます。

事前ブート認証をサポートするエンジンアダプターは、パイプラインに接続されているストレージアダプターだけでなく、プレブート記憶域にも登録をコミットする必要があります。これを実現する方法の詳細は、ベンダーに任されています。

重要

SubFactor パラメーターに指定された値の検証を試みないでください。 Windows 生体認証サービスは、指定された値を実装に渡す前に検証します。値が WINBIO_SUBTYPE_NO_INFORMATION または WINBIO_SUBTYPE_ANY場合は、必要に応じて検証します。

例

次の擬似コードは、この関数の 1 つの可能な実装を示しています。この例はコンパイルされません。目的に合わせて調整する必要があります。

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterCommitEnrollment
//
// Purpose:
//      Finalizes the enrollment object, converts it to a template, and saves 
//      the template in the database.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation
//      Identity        - GUID or SID of the template to be stored in the 
//                        database
//      SubFactor       - Sub-factor associated with the template to be stored
//                        in the database
//      PayloadBlob     - Optional pointer to an array of bytes that contain a 
//                        verification signature generated by the Windows Biometric
//                        Framework
//      PayloadBlobSize - Size, in bytes, of the character array pointed to by 
//                        the PayloadBlob parameter
//

static HRESULT
WINAPI
EngineAdapterCommitEnrollment(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_IDENTITY Identity,
    __in WINBIO_BIOMETRIC_SUBTYPE SubFactor,
    __in PUCHAR PayloadBlob,
    __in SIZE_T PayloadBlobSize
    )
{
    HRESULT hr = S_OK;
    DWORD indexVector[NUMBER_OF_TEMPLATE_BINS] = {0};
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    WINBIO_STORAGE_RECORD newTemplate = {0};

    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline) ||
        !ARGUMENT_PRESENT(Identity))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    if (ARGUMENT_PRESENT(PayloadBlob) && PayloadBlobSize == 0)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }
    
    if (!ARGUMENT_PRESENT(PayloadBlob) && PayloadBlobSize > 0)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // TODO: Verify that the SubFactor and Identity arguments are valid.

    // Retrieve the context from the pipeline.
    PWINIBIO_ENGINE_CONTEXT context = 
        (PWINIBIO_ENGINE_CONTEXT)Pipeline->EngineContext;

    // Return if an enrollment is not in progress. This example assumes that 
    // an enrollment object is part of your engine context structure.
    if (context->Enrollment.InProgress != TRUE)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    // If your adapter supports index vectors to place templates into buckets,
    // call a custom function (_AdapterCreateIndexVector) to create an index 
    // vector from the template data in the enrollment object.
    hr = _AdapterCreateIndexVector(
                context, 
                context->Enrollment.Template, 
                context->Enrollment.TemplateSize,
                indexVector, 
                NUMBER_OF_TEMPLATE_BINS, 
                &rejectDetail
                );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    newTemplate.Identity = Identity;
    newTemplate.SubFactor = SubFactor;
    newTemplate.IndexVector = indexVector;
    newTemplate.IndexElementCount = NUMBER_OF_TEMPLATE_BINS;
    newTemplate.TemplateBlob = context->Enrollment.Template;
    newTemplate.TemplateBlobSize = context->Enrollment.TemplateSize;
    newTemplate.PayloadBlob = PayloadBlob;
    newTemplate.PayloadBlobSize = PayloadBlobSize;

    hr = WbioStorageAddRecord(
                Pipeline,
                &newTemplate
                );

    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Call a custom function (_AdapterDestroyEnrollmentTemplate) to release
    // any resources held by the enrollment object.
    _AdapterDestroyEnrollmentTemplate(
        context,
        &context->Enrollment
        );

    // Specify that the enrollment process has been completed.
    context->Enrollment.InProgress = FALSE;

cleanup:

    return hr;
}

要件

要件	値
サポートされている最小のクライアント	Windows 7 [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 R2 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	winbio_adapter.h (Winbio_adapter.h を含む)

こちらもご覧ください

EngineAdapterClearContext

プラグイン関数

次の方法で共有

PIBIO_ENGINE_COMMIT_ENROLLMENT_FN コールバック関数 (winbio_adapter.h)

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

その他のリソース