PIBIO_ENGINE_IDENTIFY_FEATURE_SET_FNコールバック関数 (winbio_adapter.h)
Windows 生体認証フレームワークによって呼び出され、現在の機能セットからテンプレートを作成し、データベース内で一致するテンプレートを見つけます。 一致するものが見つかった場合、エンジン アダプターは、 Id、 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
データベースから回復されたテンプレートの GUID または SID を含む WINBIO_IDENTITY構造体への ポインター。 この値は、一致するものが見つかった場合にのみ返されます。
[out] SubFactor
データベース 内 のテンプレートに関連付けられたサブ要素を受け取るWINBIO_BIOMETRIC_SUBTYPE値。 詳細については、「解説」を参照してください。 この値は、一致するものが見つかった場合にのみ返されます。
[out] PayloadBlob
テンプレートと共に保存されたペイロード データへのポインターを受け取る変数のアドレス。 ペイロード データがない場合は、この値を NULL に設定 します。
[out] PayloadBlobSize
PayloadBlob パラメーターで指定されたバッファーのサイズをバイト単位で受け取る変数へのポインター。 ペイロード データがない場合は、この値を 0 に設定します。
[out] HashValue
テンプレートの生成されたハッシュ値へのポインターを受け取る変数のアドレス。 エンジン アダプターがハッシュ生成をサポートしていない場合は、この値を NULL に設定します。
[out] HashSize
HashValue パラメーターで指定されたバッファーのサイズをバイト単位で受け取る変数へのポインター。 エンジン アダプターがハッシュ生成をサポートしていない場合は、この値を 0 に設定します。
[out] RejectDetail
キャプチャエラーによってエンジンが一致する操作を実行できない場合に追加情報を受け取る変数へのポインター。 最新のキャプチャが成功した場合は、このパラメーターを 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 値を返してエラーを示す必要があります。
| リターン コード | 説明 |
|---|---|
|
Pipeline パラメーターが NULL です。 |
|
機能セットは、識別操作のエンジン アダプターの内部要件を満たしていませんでした。 エラーの詳細については、 RejectDetail パラメーターで指定します。 |
|
パイプラインの機能セットは、データベース内のどの ID にも対応していません。 |
解説
テンプレート ハッシュの生成に使用されるアルゴリズムは、このパイプラインで EngineAdapterSetHashAlgorithm への最新の呼び出しによって選択されたアルゴリズムです。
この関数によって返されるハッシュ値 (存在する場合) は、パイプラインにアタッチされている一致するテンプレートではなく、データベース内にある登録テンプレートのハッシュです。
PayloadBlob バッファーと HashValue バッファーは、EngineAdapterIdentifyFeatureSet 関数が正常に返された後、エンジン アダプターによって所有および管理されます。 エンジン アダプターは、 EngineAdapterClearContext の次の呼び出しまで、このパイプラインのバッファー アドレスを有効な状態に保つ必要があります。
例
次の擬似コードは、この関数の 1 つの可能な実装を示しています。 この例はコンパイルされません。 目的に合わせて調整する必要があります。
//////////////////////////////////////////////////////////////////////////////////////////
//
// 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 を含む) |
関連項目
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示