PIBIO_ENGINE_IDENTIFY_FEATURE_SET_FN回呼函式 (winbio_adapter.h)
由 Windows 生物特徵辨識架構呼叫，以從目前的功能集建置範本，並在資料庫中找出相符的範本。 如果找到相符專案，引擎配接器必須以預存範本的適當資訊填入 Identity、 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
WINBIO_IDENTITY結構的指標，其中包含從資料庫復原之範本的 GUID 或 SID。 只有在找到相符專案時，才會傳回此值。
[out] SubFactor
WINBIO_BIOMETRIC_SUBTYPE值，這個值會接收資料庫中與範本相關聯的子因素。 如需詳細資訊，請參閱＜備註＞一節。 只有在找到相符專案時，才會傳回此值。
[out] PayloadBlob
變數的位址，該變數會接收與範本一起儲存之承載資料的指標。 如果沒有承載資料，請將此值設定為 Null。
[out] PayloadBlobSize
變數的指標，該變數會接收 PayloadBlob 參數所指定的緩衝區大小，以位元組為單位。 如果沒有承載資料，請將此值設定為零。
[out] HashValue
接收範本所產生雜湊值的指標的變數位址。 如果引擎配接器不支援雜湊產生，請將此值設定為 Null。
[out] HashSize
接收 HashValue 參數所指定之緩衝區大小的變數指標，以位元組為單位。 如果引擎配接器不支援雜湊產生，請將此值設定為零。
[out] RejectDetail
如果擷取失敗導致引擎無法執行比對作業，則為接收其他資訊的變數指標。 如果最近擷取成功，請將此參數設定為零。 針對指紋擷取定義了下列值：
- 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 值，以指出錯誤。
| 傳回碼 | 描述 |
|---|---|
|
Pipeline參數為Null。 |
|
功能集不符合識別作業之引擎配接器的內部需求。 有關失敗的進一步資訊是由 RejectDetail 參數所指定。 |
|
管線中的功能集不會對應至資料庫中的任何身分識別。 |
備註
用來產生範本雜湊的演算法是在此管線上，最近呼叫至 EngineAdapterSetHashAlgorithm所選取的雜湊。
如果有任何的話，此函式所傳回的雜湊值是資料庫中找到的註冊範本雜湊，而不是附加至管線的相符範本。
EngineAdapterIdentifyFeatureSet函式成功傳回之後，引擎配接器會擁有並管理PayloadBlob和HashValue緩衝區。 引擎配接器必須讓此管線的緩衝區位址有效，直到下一次呼叫 EngineAdapterClearCoNtext為止。
範例
下列虛擬程式碼顯示此函式的一個可能實作。 此範例不會編譯。 您必須調整它以符合您的用途。
//////////////////////////////////////////////////////////////////////////////////////////
//
// 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) |