PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN コールバック関数 (winbio_adapter.h)
センサー アダプターによって実装された SensorAdapterPushDataToEngine 関数によって呼び出され、生の生体認証サンプルを受け入れて機能セットを抽出するようにエンジン アダプターに通知します。 この機能セットは、照合または登録に使用できます。
構文
PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN PibioEngineAcceptSampleDataFn;
HRESULT PibioEngineAcceptSampleDataFn(
[in, out] PWINBIO_PIPELINE Pipeline,
[in] PWINBIO_BIR SampleBuffer,
[in] SIZE_T SampleSize,
[in] WINBIO_BIR_PURPOSE Purpose,
[out] PWINBIO_REJECT_DETAIL RejectDetail
)
{...}
パラメーター
[in, out] Pipeline
操作を実行する生体認証ユニットに関連付けられている WINBIO_PIPELINE 構造体へのポインター。
[in] SampleBuffer
処理する生体認証サンプルを含む WINBIO_BIR 構造体へのポインター。
[in] SampleSize
SampleBuffer パラメーターで返されるWINBIO_BIR構造体のサイズを含むSIZE_T値。
[in] Purpose
サンプル の 使用目的を指定するWINBIO_BIR_PURPOSEビットマスク。 WINBIO_BIR_PURPOSE構造体は、キャプチャ データを使用する目的と、その最適化方法を指定します。 これには、次の値のビットごとの OR を指定できます。
- WINBIO_PURPOSE_VERIFY
- WINBIO_PURPOSE_IDENTIFY
- WINBIO_PURPOSE_ENROLL
- WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
- WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION
[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 値を返す必要があります。
| リターン コード | 説明 |
|---|---|
|
引数 SampleSize を 0 にすることはできません。 Purpose 引数は、パラメーターの説明に記載されている値のビットごとの OR である必要があります。 |
|
Pipeline、SampleBuffer、RejectDetail の各引数を NULL にすることはできません。 |
|
メモリ不足のため、操作を完了できませんでした。 |
|
データを処理して、必要な機能セットを作成できませんでした。 RejectDetail には、エラーに関する追加情報が含まれています。 |
注釈
この関数を呼び出して作成された機能セットは、関数が返された後も生体認証ユニット パイプラインに保持されます。 これは、以前の機能セットを置き換えます。
SensorAdapterPushDataToEngine 関数のセンサー アダプターの実装では、次のラッパー関数 (Winbio_adapter.h で定義) を使用して EngineAdapterAcceptSampleData を呼び出す必要があります。
HRESULT WbioEngineAcceptSampleData(
__inout PWINBIO_PIPELINE Pipeline,
__in PWINBIO_BIR SampleBuffer,
__in SIZE_T SampleSize,
__in WINBIO_BIR_PURPOSE Purpose,
__out PWINBIO_REJECT_DETAIL RejectDetail
);
SampleBuffer パラメーターで渡されるWINBIO_BIR構造体は、センサー アダプターの プロパティです。 センサー アダプターは WINBIO_BIR オブジェクトの有効期間を制御するため、 EngineAdapterAcceptSampleData 関数は構造体の割り当てを解除したり、構造体へのポインターを保存したりしないでください。 ポインターを保存しないことにより、EngineAdapterAcceptSampleData 関数が戻った後に、エンジン アダプターの他の部分がWINBIO_BIR構造体を使用することを防ぐことができます。
WINBIO_BIR構造体の StandardDataBlock メンバーの Offset フィールドが 0 より大きい場合 (BIR に標準データ形式の生体認証サンプルが含まれていることを示します)、HeaderBlock メンバーの BiometricDataFormat フィールドは次のように設定する必要があります。
- [所有者] フィールドはWINBIO_ ANSI_381_FORMAT_OWNERする必要があります。
- [種類] フィールドはWINBIO_ANSI_381_FORMAT_TYPEする必要があります。
また、Windows 生体認証フレームワークでは、 HeaderBlock メンバー ( WINBIO_BIR_HEADER 構造体) に、サンプルをキャプチャするためにセンサー アダプターによって使用される DataFlags と Purpose の値が含まれていることも前提としています。
指紋サンプルを処理し、エンジン アダプターで不適切なスワイプを拒否する指紋センサーも 、WINBIO_BIR_PURPOSEに有効な値を使用する必要があります。
例
次の擬似コードは、この関数の 1 つの可能な実装を示しています。 この例はコンパイルされません。 目的に合わせて調整する必要があります。
//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterAcceptSampleData
//
// Purpose:
// Notifies the engine adapter to accept a raw biometric sample and
// extract a feature set.
//
// Parameters:
// Pipeline - Pointer to a WINBIO_PIPELINE structure associated
// with the biometric unit performing the operation.
// SampleBuffer - Contains the biometric sample to be processed.
// SampleSize - Size of the structure returned in the SampleBuffer
// parameter.
// Purpose - Specifies the intended use of the sample.
// RejectDetail - Receives additional information about the failure,
// if any, to process a biometric sample.
//
static HRESULT
WINAPI
EngineAdapterAcceptSampleData(
__inout PWINBIO_PIPELINE Pipeline,
__in PWINBIO_BIR SampleBuffer,
__in SIZE_T SampleSize,
__in WINBIO_BIR_PURPOSE Purpose,
__out PWINBIO_REJECT_DETAIL RejectDetail
)
{
HRESULT hr = S_OK;
PUCHAR featureSet = NULL;
// Verify that pointer arguments are not NULL.
if (!ARGUMENT_PRESENT(Pipeline) ||
!ARGUMENT_PRESENT(SampleBuffer) ||
!ARGUMENT_PRESENT(RejectDetail))
{
hr = E_POINTER;
goto cleanup;
}
// Retrieve the context from the pipeline.
PWINBIO_ENGINE_CONTEXT context =
(PWINBIO_ENGINE_CONTEXT)Pipeline->EngineContext;
// Verify that input arguments are valid.
if (SampleSize == 0 ||
Purpose == WINBIO_NO_PURPOSE_AVAILABLE)
{
hr = E_INVALIDARG;
goto cleanup;
}
// Release any feature set currently attached to the pipeline before
// creating a new feature set.
if (context->FeatureSet != NULL)
{
_AdapterRelease(context->FeatureSet);
context->FeatureSet = NULL;
context->FeatureSetSize = 0;
}
// An actual engine adapter would here process the contents of the sample
// buffer, generate a feature set suitable for the purpose(s) specified
// by the Purpose parameter, and attach the feature set to the pipeline.
// The following trivial example, however, creates a feature set simply
// by making an exact copy of the raw sample.
// If the sample data cannot be processed, return an HRESULT error code
// of WINBIO_E_BAD_CAPTURE and set extended error information in the
// RejectDetail parameter.
featureSet = (PUCHAR)_AdapterAlloc(SampleSize);
if (featureSet == NULL)
{
hr = E_OUTOFMEMORY;
goto cleanup;
}
RtlCopyMemory(featureSet, SampleBuffer, SampleSize);
context->FeatureSet = featureSet;
featureSet = NULL;
context->FeatureSetSize = SampleSize;
cleanup:
if (FAILED(hr))
{
if (featureSet != NULL)
{
_AdapterRelease(featureSet);
}
}
return hr;
}
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 7 [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2008 R2 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winbio_adapter.h (Winbio_adapter.h を含む) |
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示