PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN

センサーアダプターが実装する SensorAdapterPushDataToEngine 関数から呼び出され、生の生体サンプルを受け取って特徴セットを抽出するようエンジンアダプターに通知します。この特徴セットは、照合または登録に使用できます。

関数が成功した場合は S_OK を返します。失敗した場合は、エラーを示す次のいずれかの HRESULT 値を返さなければなりません。

この関数を呼び出して作成された特徴セットは、関数から復帰した後も生体認証ユニットのパイプラインに保持されます。この特徴セットは、それ以前の特徴セットを置き換えます。

センサーアダプターにおける SensorAdapterPushDataToEngine 関数の実装では、EngineAdapterAcceptSampleData を呼び出すために、次のラッパー関数 (Winbio_adapter.h で定義されています) を使用してください:

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 フィールドがゼロより大きい場合 (BIR が標準データ形式の生体サンプルを含んでいることを示します)、HeaderBlock メンバーの BiometricDataFormat フィールドを次のように設定しなければなりません:

• Owner フィールドは WINBIO_ ANSI_381_FORMAT_OWNER でなければなりません。
• Type フィールドは 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;
}