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 结构的指针，该 GUID 或 SID 应与从数据库恢复的模板的 GUID 或 SID 匹配。
[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 值之一来指示错误。
| 返回代码 | 说明 |
|---|---|
|
强制指针参数为 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) |