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

[アーティクル]
08/27/2023

Windows 生体認証フレームワークによって呼び出され、現在の機能セットからテンプレートを作成し、データベース内で一致するテンプレートを見つけます。一致するものが見つかった場合、エンジンアダプターは、 Id、 SubFactor、 PayloadBlob パラメーターに格納されているテンプレートの適切な情報を入力する必要があります。

構文

PIBIO_ENGINE_IDENTIFY_FEATURE_SET_FN PibioEngineIdentifyFeatureSetFn;

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

パラメーター

[in, out] Pipeline

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

[out] Identity

データベースから回復されたテンプレートの GUID または SID を含む WINBIO_IDENTITY構造体へのポインター。この値は、一致するものが見つかった場合にのみ返されます。

[out] SubFactor

データベース内のテンプレートに関連付けられたサブ要素を受け取るWINBIO_BIOMETRIC_SUBTYPE値。詳細については、「解説」を参照してください。この値は、一致するものが見つかった場合にのみ返されます。

[out] PayloadBlob

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

[out] PayloadBlobSize

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

[out] HashValue

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

[out] HashSize

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

[out] RejectDetail

キャプチャエラーによってエンジンが一致する操作を実行できない場合に追加情報を受け取る変数へのポインター。最新のキャプチャが成功した場合は、このパラメーターを 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	Pipeline パラメーターが NULL です。
WINBIO_E_BAD_CAPTURE	機能セットは、識別操作のエンジンアダプターの内部要件を満たしていませんでした。エラーの詳細については、 RejectDetail パラメーターで指定します。
WINBIO_E_UNKNOWN_ID	パイプラインの機能セットは、データベース内のどの ID にも対応していません。

解説

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

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

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

例

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterIdentifyFeatureSet
//
// Purpose:
//      Build a template from the current feature set and locate a matching 
//      template in the database.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation
//      Identity        - The GUID or SID of the template recovered from the 
//                        database
//      SubFactor       - Sub-factor associated with the template in the 
//                        database
//      PayloadBlob     - Payload data saved with the template
//      PayloadBlobSize - Size, in bytes, of the buffer specified by the 
//                        PayloadBlob parameter. 
//      HashValue       - Hash value for the template
//      HashSize        - Size, in bytes, of the buffer specified by the 
//                        HashValue parameter.
//      RejectDetail    - Receives additional information if a capture 
//                        failure prevents the engine from performing a matching 
//                        operation.
//      
static HRESULT
WINAPI
EngineAdapterIdentifyFeatureSet(
    __inout PWINBIO_PIPELINE Pipeline,
    __out PWINBIO_IDENTITY Identity,
    __out PWINBIO_BIOMETRIC_SUBTYPE SubFactor,
    __out PUCHAR *PayloadBlob,
    __out PSIZE_T PayloadBlobSize,
    __out PUCHAR *HashValue,
    __out PSIZE_T HashSize,
    __out PWINBIO_REJECT_DETAIL RejectDetail
    )
{
    HRESULT hr = S_OK;
    SIZE_T recordCount = 0;
    SIZE_T index = 0;
    WINBIO_STORAGE_RECORD thisRecord;
    BOOLEAN match = FALSE;
    DWORD indexVector[NUMBER_OF_TEMPLATE_BINS] = {0};

    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline) ||
        !ARGUMENT_PRESENT(Identity) ||
        !ARGUMENT_PRESENT(SubFactor) ||
        !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.
    ZeroMemory( Identity, sizeof(WINBIO_IDENTITY));
    Identity->Type = WINBIO_ID_TYPE_NULL;
    *SubFactor          = WINBIO_SUBTYPE_NO_INFORMATION;
    *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;
    }

    // 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 feature set. In this example, the
    // engine adapter context attached to the pipeline contains a FeatureSet
    // member.
    hr = _AdapterCreateIndexVector(
                context, 
                context->FeatureSet,
                context->FeatureSetSize,
                indexVector, 
                NUMBER_OF_TEMPLATE_BINS, 
                RejectDetail
                );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Retrieve the records in the index vector. If your adapter does not support 
    // index vectors (the vector length is zero), calling the WbioStorageQueryByContent 
    // function will retrieve all records.
    // WbioStorageQueryByContent is a wrapper function in the Winbio_adapter.h 
    // header file.
    hr = WbioStorageQueryByContent(
            Pipeline,
            WINBIO_SUBTYPE_ANY,
            indexVector,
            NUMBER_OF_TEMPLATE_BINS
            );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Determine the size of the result set. WbioStorageGetRecordCount is a wrapper
    // function in the Winbio_adapter.h header file.
    hr = WbioStorageGetRecordCount( Pipeline, &recordCount);
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Point the result set cursor at the first record. WbioStorageFirstRecord
    // is a wrapper function in the Winbio_adapter.h header file.
    hr = WbioStorageFirstRecord( Pipeline );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Iterate through all records in the result set and determine which record
    // matches the current feature set. WbioStorageGetCurrentRecord is a wrapper
    // function in the Winbio_adapter.h header file.
    for (index = 0; index < recordCount; ++index)
    {
        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 storage.
        // 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) && hr != WINBIO_E_NO_MATCH)
        {
            goto cleanup;
        }
        if (match)
        {
            break;
        }

        hr = WbioStorageNextRecord( Pipeline );
        if (FAILED(hr))
        {
            if (hr == WINBIO_E_DATABASE_NO_MORE_RECORDS)
            {
                hr = S_OK;
                break;
            }
            else
            {
                goto cleanup;
            }
        }
    }

    if (match)
    {
        // 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;
        }

        // Return information about the matching template to the caller.
        CopyMemory( Identity, thisRecord.Identity, sizeof(WINBIO_IDENTITY));

        *SubFactor          = thisRecord.SubFactor;
        *PayloadBlob        = thisRecord.PayloadBlob;
        *PayloadBlobSize    = thisRecord.PayloadBlobSize;
        *HashValue          = &context->HashBuffer;
        *HashSize           = context->HashSize;
    }
    else
    {
        hr = WINBIO_E_UNKNOWN_ID;
    }

cleanup:

    if (hr == WINBIO_E_DATABASE_NO_RESULTS)
    {
        hr = WINBIO_E_UNKNOWN_ID;
    }
    return hr;
}

要件


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

次の方法で共有

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

構文

パラメーター

戻り値

解説

例

要件

関連項目

フィードバック

その他のリソース