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 之 WINBIO_IDENTITY 結構的指標。

[in] SubFactor

WINBIO_BIOMETRIC_SUBTYPE值，預期符合從資料庫復原的範本值。如需詳細資訊，請參閱＜備註＞一節。

[out] Match

布爾值的指標，指定 Identity 和 SubFactor 參數是否符合從資料庫復原的範本參數。 TRUE 指定這些值相符。

[out] PayloadBlob

變數的位址，該變數會接收與範本一起儲存之承載數據的指標。如果沒有承載數據，請將此值設定為 NULL。

[out] PayloadBlobSize

值指標，接收 PayloadBlob 參數所指定之緩衝區的大小，以位元組為單位。如果沒有與範本一起儲存的承載數據，請將此值設定為零。

[out] HashValue

接收範本哈希指標的變數位址。如果引擎配接器不支援哈希產生，請將此值設定為 NULL。

[out] HashSize

值指標，其中包含 HashValue 參數所指定哈希的大小，以位元組為單位。如果引擎配接器不支援哈希產生，請將此值設定為零。

[out] RejectDetail

如果擷取失敗導致引擎無法執行比對作業，則 WINBIO_REJECT_DETAIL值的指標 ，以接收其他資訊。如果最新的擷取成功，請將此參數設定為零。為指紋擷取定義下列值

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 值，以指出錯誤。

傳回碼	Description
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 函式所選取的演算法。

如果有任何哈希值，則此函式所傳回的哈希值是資料庫中找到的註冊範本哈希，而不是附加至管線的相符範本。

EngineAdapterIdentifyFeatureSet 函式成功傳回之後，引擎配接器會擁有並管理 PayloadBlob 和 HashValue 緩衝區。引擎配接器必須讓此管線的緩衝區位址保持有效，直到下一次呼叫 EngineAdapterClearContext 為止。

範例

下列虛擬程式代碼顯示此函式的一個可能實作。此範例不會編譯。您必須調整它以符合您的用途。

//////////////////////////////////////////////////////////////////////////////////////////
//
// 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)

語法

參數

傳回值

備註

範例

規格需求

另請參閱

意見反應

其他資源