Share via

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

  • [アーティクル]

Windows 生体認証フレームワークによって呼び出され、標準の WINBIO_BIR 構造として書式設定されたエンジンから、最後に処理された機能セットまたはテンプレートのコピーを取得します。

構文

PIBIO_ENGINE_EXPORT_ENGINE_DATA_FN PibioEngineExportEngineDataFn;

HRESULT PibioEngineExportEngineDataFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      WINBIO_BIR_DATA_FLAGS Flags,
  [out]     PWINBIO_BIR *SampleBuffer,
  [out]     PSIZE_T SampleSize
)
{...}

パラメーター

[in, out] Pipeline

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

[in] Flags

エンジンによって返される WINBIO_BIR 構造体のプロパティを示す 値。 これは、次のセキュリティ および処理レベル フラグのビットごとの 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_DATA_FLAG_INTERMEDIATE データは生ではなく、完全に処理されていません。

  • WINBIO_DATA_FLAG_PROCESSED データが処理されました。

[out] SampleBuffer

機能セットまたはテンプレートを含む WINBIO_BIR 構造体へのポインターを受け取る変数のアドレス。

[out] SampleSize

SampleBuffer パラメーターで返されるWINBIO_BIR構造体のサイズ (バイト単位) を含む変数へのポインター。

戻り値

関数が成功した場合は、S_OK を返します。 関数が失敗した場合は、次のいずれかの HRESULT 値を返してエラーを示す必要があります。

リターン コード 説明
E_INVALIDARG
 エンジン アダプターは、 Flags パラメーターで指定されたフラグの組み合わせをサポートしていません。
E_OUTOFMEMORY
 WINBIO_BIR構造体を作成するのに十分なメモリがありません。
E_POINTER
 必須のポインター パラメーターは NULL です。
WINBIO_E_INVALID_DEVICE_STATE
 パイプラインには、 Flags パラメーターに必要なデータの型が含まれていません。
E_NOTIMPL
 このメソッドは、現在実装されていません。

注釈

HeapAlloc 関数を使用して、SampleBuffer パラメーターで返されるバッファーをプロセス ヒープから割り当てる必要があります。 バッファーが作成されると、Windows 生体認証フレームワークの プロパティになります。 フレームワークでは、このメモリの使用が完了すると割り当てが解除されるため、この関数の実装でバッファーの割り当てを解除したり、そのメモリへのポインターを保存したりしないでください。 ポインターを保存しないことで、エンジン アダプターの他の部分がこの関数から戻った後にバッファーの使用を試みないようにします。

例

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterExportEngineData
//
// Purpose:
//      Retrieves a copy of the most recently processed feature set or template.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation
//      Flags           - Security and processing level flags
//      SampleBuffer    - Contains the feature set or template
//      SampleSize      - Size, in bytes, of the structure returned in the 
//                        SampleBuffer parameter.
//
static HRESULT
WINAPI
EngineAdapterExportEngineData(
    __inout PWINBIO_PIPELINE Pipeline,
    __in WINBIO_BIR_DATA_FLAGS Flags,
    __out PWINBIO_BIR *SampleBuffer,
    __out PSIZE_T SampleSize
    )
{
    HRESULT hr = S_OK;
    PWINBIO_BIR birAddress = NULL;
    SIZE_T birSize = 0;

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

    // Retrieve the context from the pipeline.
    PWINBIO_ENGINE_CONTEXT context = 
           (PWINBIO_ENGINE_CONTEXT)Pipeline->EngineContext;

    // At least one processing level flag must be set. Your adapter can also
    // place additional restrictions on supported export formats.
    if (Flags & (WINBIO_DATA_FLAG_RAW | 
                 WINBIO_DATA_FLAG_INTERMEDIATE | 
                 WINBIO_DATA_FLAG_PROCESSED) == 0)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // You must implement the _CreateBirFromAdapterData function to extract
    // data from the engine context and create a new WINBIO_BIR structure. The
    // function passes ownership of the new biometric information record (BIR)
    // to the EngineAdapterExportEngineData routine which then passes the BIR
    // to the caller.
    hr = _CreateBirFromAdapterData( context, Flags, &birAddress, &birSize);
    if (SUCCEEDED(hr))
    {
        *SampleBuffer = birAddress;
        *SampleSize = birSize;
    }

cleanup:

    return hr;
}

要件

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

こちらもご覧ください

EngineAdapterAcceptSampleData

プラグイン関数