コールバック関数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 と一致することが予想される GUID または SID を含む WINBIO_IDENTITY構造体への ポインター。
[in] SubFactor
データベースから回復されたテンプレート の値と 一致すると予想されるWINBIO_BIOMETRIC_SUBTYPE値。 詳細については、「解説」を参照してください。
[out] Match
Identity パラメーターと SubFactor パラメーターがデータベースから回復されたテンプレートのパラメーターと一致するかどうかを指定するブール値へのポインター。 TRUE は 、これらの値が一致することを指定します。
[out] PayloadBlob
テンプレートと共に保存されたペイロード データへのポインターを受け取る変数のアドレス。 ペイロード データがない場合は、この値を NULL に設定 します。
[out] PayloadBlobSize
PayloadBlob パラメーターで指定されたバッファーのサイズ (バイト単位) を受け取る値へのポインター。 テンプレートと共に格納されているペイロード データがない場合は、この値を 0 に設定します。
[out] HashValue
テンプレートのハッシュへのポインターを受け取る変数のアドレス。 エンジン アダプターがハッシュ生成をサポートしていない場合は、この値を NULL に設定します。
[out] HashSize
HashValue パラメーターで指定されたハッシュのサイズ (バイト単位) を含む値へのポインター。 エンジン アダプターがハッシュ生成をサポートしていない場合は、この値を 0 に設定します。
[out] RejectDetail
キャプチャ エラーによってエンジン が一致する操作を実行できない場合に追加情報を受け取るWINBIO_REJECT_DETAIL値へのポインター。 最新のキャプチャが成功した場合は、このパラメーターを 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 値を返す必要があります。
| リターン コード | 説明 |
|---|---|
|
必須ポインター パラメーターは 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場合は、必要に応じて検証します。
この関数によって返されるハッシュ値 (存在する場合) は、パイプラインにアタッチされている一致するテンプレートではなく、データベースで見つかった登録テンプレートのハッシュです。
PayloadBlob バッファーと HashValue バッファーは、EngineAdapterIdentifyFeatureSet 関数が正常に返された後、エンジン アダプターによって所有および管理されます。 エンジン アダプターは、 次に EngineAdapterClearContext を呼び出すまで、このパイプラインのバッファー アドレスを有効な状態に保つ必要があります。
例
次の擬似コードは、この関数の 1 つの可能な実装を示しています。 この例はコンパイルされません。 目的に合わせて調整する必要があります。
//////////////////////////////////////////////////////////////////////////////////////////
//
// 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 を含む) |