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

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

現在の機能セット内のテンプレートをデータベース内の特定のテンプレートと比較するために、Windows 生体認証フレームワークによって呼び出されます。テンプレートが同等の場合、エンジンアダプターは Match パラメーターが指すブール値を TRUE に設定し、 PayloadBlob パラメーターで一致したテンプレートを返し、 HashValue パラメーターでテンプレートのハッシュを返す必要があります。

構文

PIBIO_ENGINE_VERIFY_FEATURE_SET_FN PibioEngineVerifyFeatureSetFn;

HRESULT PibioEngineVerifyFeatureSetFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      PWINBIO_IDENTITY Identity,
  [in]      WINBIO_BIOMETRIC_SUBTYPE SubFactor,
  [out]     PBOOLEAN Match,
  [out]     PUCHAR *PayloadBlob,
  [out]     PSIZE_T PayloadBlobSize,
  [out]     PUCHAR *HashValue,
  [out]     PSIZE_T HashSize,
  [out]     PWINBIO_REJECT_DETAIL RejectDetail
)
{...}

パラメーター

[in, out] Pipeline

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

[in] Identity

データベースから回復されたテンプレートの GUID または SID と一致することが予想される GUID または SID を含む WINBIO_IDENTITY構造体へのポインター。

[in] SubFactor

データベースから回復されたテンプレート の値と 一致すると予想されるWINBIO_BIOMETRIC_SUBTYPE値。詳細については、「解説」を参照してください。

[out] Match

Identity パラメーターと SubFactor パラメーターがデータベースから回復されたテンプレートのパラメーターと一致するかどうかを指定するブール値へのポインター。 TRUE は 、これらの値が一致することを指定します。

[out] PayloadBlob

テンプレートと共に保存されたペイロードデータへのポインターを受け取る変数のアドレス。ペイロードデータがない場合は、この値を NULL に設定 します。

[out] PayloadBlobSize

PayloadBlob パラメーターで指定されたバッファーのサイズ (バイト単位) を受け取る値へのポインター。テンプレートと共に格納されているペイロードデータがない場合は、この値を 0 に設定します。

[out] HashValue

テンプレートのハッシュへのポインターを受け取る変数のアドレス。エンジンアダプターがハッシュ生成をサポートしていない場合は、この値を NULL に設定します。

[out] HashSize

HashValue パラメーターで指定されたハッシュのサイズ (バイト単位) を含む値へのポインター。エンジンアダプターがハッシュ生成をサポートしていない場合は、この値を 0 に設定します。

[out] RejectDetail

キャプチャ エラーによってエンジン が一致する操作を実行できない場合に追加情報を受け取るWINBIO_REJECT_DETAIL値へのポインター。最新のキャプチャが成功した場合は、このパラメーターを 0 に設定します。指紋キャプチャには、次の値が定義されています

WINBIO_FP_TOO_HIGH
WINBIO_FP_TOO_LOW
WINBIO_FP_TOO_LEFT
WINBIO_FP_TOO_RIGHT
WINBIO_FP_TOO_FAST
WINBIO_FP_TOO_SLOW
WINBIO_FP_POOR_QUALITY
WINBIO_FP_TOO_SKEWED
WINBIO_FP_TOO_SHORT
WINBIO_FP_MERGE_FAILURE

戻り値

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

リターンコード	説明
E_POINTER	必須ポインターパラメーターは NULL です。
E_INVALIDARG	SubFactor パラメーターで指定された値が正しくありません。
WINBIO_E_BAD_CAPTURE	機能セットが、検証操作のエンジンアダプターの内部要件を満たしていません。エラーの詳細については、 RejectDetail パラメーターで指定します。
WINBIO_E_NO_MATCH	パイプライン内の機能セットは、データベースに格納されている機能と一致しますが、 Identity パラメーターと SubFactor パラメーターで渡される値の組み合わせには対応していません。

注釈

SubFactor パラメーターは、生体認証テンプレートに関連付けられているサブ要素を指定します。 Windows 生体認証フレームワークは指紋キャプチャのみをサポートし、次の定数を使用してサブタイプ情報を表すことができます。

WINBIO_ANSI_381_POS_RH_THUMB
WINBIO_ANSI_381_POS_RH_INDEX_FINGER
WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER
WINBIO_ANSI_381_POS_RH_RING_FINGER
WINBIO_ANSI_381_POS_RH_LITTLE_FINGER
WINBIO_ANSI_381_POS_LH_THUMB
WINBIO_ANSI_381_POS_LH_INDEX_FINGER
WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER
WINBIO_ANSI_381_POS_LH_RING_FINGER
WINBIO_ANSI_381_POS_LH_LITTLE_FINGER
WINBIO_SUBTYPE_ANY

重要

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

テンプレートハッシュの生成に使用されるアルゴリズムは、 EngineAdapterSetHashAlgorithm 関数に対するこのパイプラインの最新の呼び出しで選択されたアルゴリズムです。

この関数によって返されるハッシュ値 (存在する場合) は、パイプラインにアタッチされている一致するテンプレートではなく、データベースで見つかった登録テンプレートのハッシュです。

PayloadBlob バッファーと HashValue バッファーは、EngineAdapterIdentifyFeatureSet 関数が正常に返された後、エンジンアダプターによって所有および管理されます。エンジンアダプターは、次に EngineAdapterClearContext を呼び出すまで、このパイプラインのバッファーアドレスを有効な状態に保つ必要があります。

例

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterVerifyFeatureSet
//
// Purpose:
//      Compares the template in the current feature set with a specific 
//      template in the database.
//      
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation
//      Identity        - GUID or SID that is expected to match that of the 
//                        template recovered from the database
//      SubFactor       - A WINBIO_BIOMETRIC_SUBTYPE value that is expected 
//                        to match that of the template recovered from the 
//                        database
//      Match           - A Boolean value that specifies whether the Identity 
//                        and SubFactor parameters match those of the template
//                        recovered from the database
//      PayloadBlob     - Payload data saved with the template
//      PayloadBlobSize - Size, in bytes, of the buffer specified in the 
//                        PayloadBlob parameter
//      HashValue       - Hash of the template
//      HashSize        - Size, in bytes, of the hash specified by the 
//                        HashValue parameter
//      RejectDetail    - Receives additional information if a capture failure 
//                        prevents the engine from performing a matching operation
// 
static HRESULT
WINAPI
EngineAdapterVerifyFeatureSet(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_IDENTITY Identity,
    __in WINBIO_BIOMETRIC_SUBTYPE SubFactor,
    __out PBOOLEAN Match,
    __out PUCHAR *PayloadBlob,
    __out PSIZE_T PayloadBlobSize,
    __out PUCHAR *HashValue,
    __out PSIZE_T HashSize,
    __out PWINBIO_REJECT_DETAIL RejectDetail
    )
{
    HRESULT hr = S_OK;
    WINBIO_STORAGE_RECORD thisRecord;
    BOOLEAN match = FALSE;
    WINBIO_REJECT_DETAIL rejectDetail = 0;

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

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

    // Initialize the return values.
    *Match              = FALSE;
    *PayloadBlob        = NULL;
    *PayloadBlobSize    = 0;
    *HashValue          = NULL;
    *HashSize           = 0;
    *RejectDetail       = 0;

    // The biometric unit cannot perform verification or identification
    // operations while it is performing an enrollment sequence.
    if (context->Enrollment.InProgress == TRUE)
    {
        hr = WINBIO_E_ENROLLMENT_IN_PROGRESS;
        goto cleanup;
    }

    // Query the storage adapter to determine whether the Identity and 
    // SubFactor combination specified on input are in the database. If
    // they are not, there can be no match. WbioStorageQueryBySubject
    // is a wrapper function defined in the Winbio_adapter.h header file.
    hr = WbioStorageQueryBySubject( Pipeline, Identity, SubFactor);
    if (FAILED(hr))
    {
        if (hr == WINBIO_E_DATABASE_NO_RESULTS)
        {
            hr = WINBIO_E_NO_MATCH;
        }
        goto cleanup;
    }

    // Position the cursor on the first record in the database. 
    // WbioStorageFirstRecord is a wrapper function defined in the 
    // Winbio_adapter.h header file.
    hr = WbioStorageFirstRecord( Pipeline );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Retrieve the current template record for the Identity and SubFactor 
    // combination specified on input. 
    hr = WbioStorageGetCurrentRecord( Pipeline, &thisRecord );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Call a custom function (_AdapterCompareTemplateToCurrentFeatureSet)
    // to compare the feature set attached to the pipeline with the template 
    // retrieved from the database.
    // If the template and feature set do not match, return WINBIO_E_NO_MATCH
    // and set the Match parameter to FALSE.
    // If your custom function cannot process the feature set, return 
    // WINBIO_E_BAD_CAPTURE and set extended error information in the 
    // RejectDetail parameter.
    hr = _AdapterCompareTemplateToCurrentFeatureSet( 
                context, 
                context->FeatureSet,
                context->FeatureSetSize,
                thisRecord.TemplateBlob, 
                thisRecord.TemplateBlobSize,
                &match,
                RejectDetail 
                );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // If there is a match and if your engine adapter supports template
    // hashing, call a custom function (_AdapterGenerateHashForTemplate)
    // to calculate the hash. Save the hash value in the context area of
    // the engine adapter.
    // Skip this step if your adapter does not support template hashing.
    hr = _AdapterGenerateHashForTemplate(
                context,
                thisRecord.TemplateBlob, 
                thisRecord.TemplateBlobSize,
                context->HashBuffer,
                &context->HashSize
                );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Set the return values.
    *Match              = TRUE;
    *PayloadBlob        = thisRecord.PayloadBlob;
    *PayloadBlobSize    = thisRecord.PayloadBlobSize;
    *HashValue          = &context->HashBuffer;
    *HashSize           = context->HashSize;

cleanup:

    if (hr == WINBIO_E_DATABASE_NO_RESULTS)
    {
        hr = WINBIO_E_NO_MATCH;
    }

    return hr;
}

要件

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

こちらもご覧ください

EngineAdapterIdentifyFeatureSet

プラグイン関数

次の方法で共有

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

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

その他のリソース