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

[アーティクル]
03/03/2024

Windows 生体認証フレームワークによって呼び出され、サンプルバッファーの現在の内容をエンジンアダプターで使用できるようにします。

構文

PIBIO_SENSOR_PUSH_DATA_TO_ENGINE_FN PibioSensorPushDataToEngineFn;

HRESULT PibioSensorPushDataToEngineFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      WINBIO_BIR_PURPOSE Purpose,
  [in]      WINBIO_BIR_DATA_FLAGS Flags,
  [out]     PWINBIO_REJECT_DETAIL RejectDetail
)
{...}

パラメーター

[in, out] Pipeline

操作を実行する生体認証ユニットに関連付けられている WINBIO_PIPELINE 構造体へのポインター。

[in] Purpose

エンジンに渡される WINBIO_BIR 構造体のプロパティを示す値です。これは、次のセキュリティおよび処理レベルフラグのビットごとの OR にすることができます。

WINBIO_PURPOSE_VERIFY
WINBIO_PURPOSE_IDENTIFY
WINBIO_PURPOSE_ENROLL
WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[in] Flags

サンプルの形式を示す値です。これは、次のセキュリティおよび処理レベルフラグのビットごとの OR にすることができます。

WINBIO_DATA_FLAG_PRIVACY

サンプルは暗号化する必要があります。

WINBIO_DATA_FLAG_INTEGRITY

このサンプルは、デジタル署名されているか、メッセージ認証コード (MAC) によって保護されている必要があります。

WINBIO_DATA_FLAG_SIGNED

このフラグとWINBIO_DATA_FLAG_INTEGRITY フラグが設定されている場合は、サンプルに署名する必要があります。このフラグが設定されていないが、WINBIO_DATA_FLAG_INTEGRITY フラグが設定されている場合は、MAC を計算する必要があります。

WINBIO_DATA_FLAG_RAW

サンプルは、キャプチャされた形式で WINBIO_BIR オブジェクトに配置する必要があります。

[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_POINTER	必須のポインター引数は NULL です。
WINBIO_E_BAD_CAPTURE	サンプルデータは使用に適していません。このエラーコードを返す場合は、 RejectDetail パラメーターに値を指定して、問題の性質を示す必要もあります。
WINBIO_E_INVALID_DEVICE_STATE	Pipeline 引数が指すWINBIO_PIPELINE構造体の SensorContext メンバーは NULL です。
WINBIO_E_NO_CAPTURE_DATA	キャプチャデータが存在しません。

注釈

この関数の実装では、サンプルバッファーに含まれる生データを標準のWINBIO_BIR 構造体に変換し、 EngineAdapterAcceptSampleData 関数を使用してこの構造体をエンジンにプッシュする必要があります。これを行う正しい方法は、Winbio_adapter.h ヘッダーファイルで定義されている WbioEngineAcceptSampleData ヘルパー関数を呼び出す方法です。

EngineAdapterAcceptSampleData 関数がWINBIO_E_BAD_CAPTUREを返す場合、SensorAdapterPushDataToEngine の実装では、エンジンアダプターによって伝達される RejectDetail 値を返す必要があります。

センサーアダプターは、 EngineAdapterAcceptSampleData に渡されるサンプルバッファーの所有権を保持します。センサーアダプターは、 EngineAdapterAcceptSampleData が返された後のある時点でこのバッファーを解放します。

例

次の擬似コードは、この関数の 1 つの可能な実装を示しています。この例はコンパイルされません。目的に合わせて調整する必要があります。

//////////////////////////////////////////////////////////////////////////////////////////
//
// SensorAdapterPushDataToEngine
//
// Purpose:
//      Makes the current contents of the sample buffer available to the 
//      engine adapter.
//      
// Parameters:
//      Pipeline     -  Pointer to a WINBIO_PIPELINE structure associated with 
//                      the biometric unit.
//      Purpose      -  Specifies the properties of the WINBIO_BIR structure 
//                      that will be passed to the engine.
//      Flags        -  A value that specifies the format of the sample.
//      RejectDetail -  Pointer to a WINBIO_REJECT_DETAIL value that receives 
//                      additional information about the reason the sample
//                      buffer is empty.
//
static HRESULT
WINAPI
SensorAdapterPushDataToEngine(
    __inout PWINBIO_PIPELINE Pipeline,
    __in WINBIO_BIR_PURPOSE Purpose,
    __in WINBIO_BIR_DATA_FLAGS Flags,
    __out PWINBIO_REJECT_DETAIL RejectDetail
    )
{
    HRESULT hr = S_OK;

    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline) ||
        !ARGUMENT_PRESENT(RejectDetail))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Retrieve the context from the pipeline.
    PWINBIO_SENSOR_CONTEXT sensorContext = 
                 (PWINBIO_SENSOR_CONTEXT)Pipeline->SensorContext;

    // Verify the state of the pipeline.
    if (sensorContext == NULL)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    if (sensorContext->CaptureBuffer != NULL &&
        sensorContext->CaptureBufferSize >= sizeof (WINBIO_CAPTURE_DATA) &&
        sensorContext->CaptureBuffer->CaptureData.Size != 0 &&
        sensorContext->CaptureBuffer->SensorStatus == WINBIO_SENSOR_ACCEPT)
    {
        // There is valid capture data in the Pipeline. Call the 
        // WbioEngineAcceptSampleData function to notify the engine adapter, but
        // retain ownership of the buffer in the sensor adapter. 
        // WbioEngineAcceptSampleData is a wrapper function declared in the
        // Winbio_adapter.h header file.
        hr = WbioEngineAcceptSampleData(
                    Pipeline,
                    (PWINBIO_BIR)sensorContext->CaptureBuffer->CaptureData.Data,
                    sensorContext->CaptureBuffer->CaptureData.Size,
                    Purpose,
                    RejectDetail
                    );
    }
    else if (sensorContext->CaptureBuffer != NULL &&
             sensorContext->CaptureBufferSize >= sizeof (WINBIO_CAPTURE_DATA) &&
             sensorContext->CaptureBuffer->WinBioHresult == WINBIO_E_BAD_CAPTURE)
    {
        // The most recent capture was not acceptable.  Do not attempt to push 
        // the sample to the engine. Instead, simply return the reject detail
        // information generated by the previous capture.
        hr = sensorContext->CaptureBuffer->WinBioHresult;
        *RejectDetail = sensorContext->CaptureBuffer->RejectDetail;
    }
    else
    {
        hr = WINBIO_E_NO_CAPTURE_DATA;
    }

    return hr;
}

要件

要件	値
サポートされている最小のクライアント	Windows 7 [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 R2 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	winbio_adapter.h (Winbio_adapter.h を含む)

こちらもご覧ください

プラグイン関数

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

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

フィードバック

その他のリソース