PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN コールバック関数 (winbio_adapter.h)

[アーティクル]
08/27/2023

センサーアダプターによって実装された 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 値を返す必要があります。

リターンコード	説明
E_INVALIDARG	引数 SampleSize を 0 にすることはできません。 Purpose 引数は、パラメーターの説明に記載されている値のビットごとの OR である必要があります。
E_POINTER	Pipeline、SampleBuffer、RejectDetail の各引数を NULL にすることはできません。
E_OUTOFMEMORY	メモリ不足のため、操作を完了できませんでした。
WINBIO_E_BAD_CAPTURE	データを処理して、必要な機能セットを作成できませんでした。 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 生体認証フレームワークでサポートされている唯一の標準データ形式です。

また、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 を含む)

こちらもご覧ください

EngineAdapterExportEngineData

プラグイン関数

次の方法で共有

PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN コールバック関数 (winbio_adapter.h)

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

その他のリソース