PIBIO_ENGINE_VERIFY_FEATURE_SET_FN回呼函式 (winbio_adapter.h)
由 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 |
|---|---|
|
強制指標參數為 NULL。 |
|
SubFactor 參數中指定的值不正確。 |
|
功能集不符合驗證作業之引擎配接器的內部需求。 失敗的進一步資訊是由 RejectDetail 參數所指定。 |
|
管線中的功能集會比對儲存在資料庫中的功能集，但不會對應至 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，請適當地驗證。
如果有任何哈希值，則此函式所傳回的哈希值是資料庫中找到的註冊範本哈希，而不是附加至管線的相符範本。
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) |