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

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

新しいデータベースを作成して構成するために、Windows 生体認証フレームワークによって呼び出されます。

構文

PIBIO_STORAGE_CREATE_DATABASE_FN PibioStorageCreateDatabaseFn;

HRESULT PibioStorageCreateDatabaseFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      PWINBIO_UUID DatabaseId,
  [in]      WINBIO_BIOMETRIC_TYPE Factor,
  [in]      PWINBIO_UUID Format,
  [in]      LPCWSTR FilePath,
  [in]      LPCWSTR ConnectString,
  [in]      SIZE_T IndexElementCount,
  [in]      SIZE_T InitialSize
)
{...}

パラメーター

[in, out] Pipeline

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

[in] DatabaseId

データベースを一意に識別する GUID へのポインター。これは、レジストリにデータベースを登録するために使用されるのと同じ GUID です。

[in] Factor

このデータベースに格納されている生体認証要素の種類を指定するWINBIO_BIOMETRIC_TYPE値。現在 、WINBIO_TYPE_FINGERPRINT のみがサポートされています。

[in] Format

WINBIO_BIR オブジェクトの VendorDataBlock メンバー内のデータのベンダー定義形式を指定する GUID へのポインター。

[in] FilePath

データベースの完全修飾ファイルパスを含む NULL で終わる Unicode 文字列へのポインター。

[in] ConnectString

データベースの NULL で終わる Unicode 接続文字列へのポインター。

[in] IndexElementCount

インデックスベクター内の要素の数。これは、0 以上にすることができます。

[in] InitialSize

データベースの開始サイズをバイト単位で格納する値。

戻り値

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

リターンコード	説明
E_POINTER	必須のポインター引数は NULL です。
WINBIO_E_INVALID_DEVICE_STATE	パイプラインオブジェクトの StorageContext メンバーが NULL です。

注釈

StorageAdapterOpenDatabase 関数が失敗し、AutoCreate フラグがレジストリ内のデータベースに関連付けられている場合、生体認証サービスはこのメソッドを呼び出します。

この関数が成功した場合、データベースは開いている状態のままにしておく必要があります。 Windows 生体認証フレームワークでは、この関数の後続の呼び出しは発行されません。

例

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

/////////////////////////////////////////////////////////////////////////////////////////
//
// StorageAdapterCreateDatabase
//
// Purpose:
//      Creates and configures a new database.
//
// Parameters:
//      Pipeline          - Pointer to a WINBIO_PIPELINE structure associated with 
//                          the biometric unit performing the operation.
//      DatabaseId        - Pointer to a GUID that uniquely identifies the database.
//      Factor            - A WINBIO_BIOMETRIC_TYPE value that specifies the type 
//                          of the biometric factor stored in the database.
//      Format            - Pointer to a GUID that specifies the vendor-defined format
//                          of the data
//      FilePath          - Pointer to the database file path.
//      ConnectString     - Pointer to the database connection string.
//      IndexElementCount - Number of elements in the index vector.
//      InitialSize       - Beginning size of the database, in bytes.
//
// Note:
//      The following example assumes that the database file has the following format:
//
//          [protected area]
//          [header]
//          [record 0]
//          [record 1]
//              .
//              .
//              .
//          [record N]
//
//      It is the responsibility of the storage adapter writer to implement protection
//      and to determine how and where encryption keys are stored.
//
static HRESULT
WINAPI
StorageAdapterCreateDatabase(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_UUID DatabaseId,
    __in WINBIO_BIOMETRIC_TYPE Factor,
    __in PWINBIO_UUID Format,
    __in LPCWSTR FilePath,
    __in LPCWSTR ConnectString,
    __in SIZE_T IndexElementCount,
    __in SIZE_T InitialSize
    )
{
    UNREFERENCED_PARAMETER(InitialSize);

    HRESULT hr = S_OK;
    struct _MY_ADAPTER_FILE_HEADER fileHeader = {0};
    BOOL fileOpen = FALSE;
    HANDLE fileHandle = INVALID_HANDLE_VALUE;
    struct _MY_ADAPTER_DPAPI_DATA protectedData = {0};
 
    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline) ||
        !ARGUMENT_PRESENT(DatabaseId) ||
        !ARGUMENT_PRESENT(Format) ||
        !ARGUMENT_PRESENT(FilePath) ||
        !ARGUMENT_PRESENT(ConnectString))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Retrieve the context from the pipeline.
    PWINBIO_STORAGE_CONTEXT storageContext = 
           (PWINBIO_STORAGE_CONTEXT)Pipeline->StorageContext;

    // Verify the pipeline state.
    if (storageContext == NULL ||
        Pipeline->StorageHandle != INVALID_HANDLE_VALUE)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    // Call a custom function (_InitializeFileHeader) to copy database 
    // attributes into a structure to be used by the file management routines
    // in the adapter.
    hr = _InitializeFileHeader(
            DatabaseId,
            Factor,
            Format,
            IndexElementCount,
            &fileHeader
            );
    if (FAILED(hr))
    {
        hr = WINBIO_E_DATABASE_CANT_CREATE;
        goto cleanup;
    }

    // Call a custom file management function (_CreateDatabase) to create
    // and open the database. Because the database is new, this function 
    // should generate a random key that can be used to encrypt and 
    // decrypt biometric templates stored in the database. The key should be
    // saved in the protected data area of the file. We recommend that you
    // encrypt the key by using the Data Protection API (DPAPI).
    hr = _CreateDatabase(
            &fileHeader,
            FilePath,
            &fileHandle,
            &protectedData
            );
    if (FAILED(hr))
    {
        goto cleanup;
    }
    fileOpen = TRUE;


    // Call a custom function (_InitializeCryptoContext) to extract the template
    // decryption key from the protected block of the database and use other
    // appropriate values from that block as necessary to set up CNG cryptography 
    // algorithms. This function should associate the CNG cryptography handles 
    // with the storage context.
    hr = _InitializeCryptoContext(
            &protectedData,
            &storageContext->CryptoContext
            );
    if (FAILED(hr))
    {
        hr = WINBIO_E_DATABASE_CANT_CREATE;
        goto cleanup;
    }

    // Attach the database file handle to the pipeline.
    Pipeline->StorageHandle = fileHandle;
    fileHandle = INVALID_HANDLE_VALUE;

    // Copy various database parameters to the storage context. The following 
    // example code assumes that the context contains fields for the following
    // items:
    //      - Number of index elements
    //      - File version number
    //      - Template format
    //      - Database ID 
    //      - Database file path
    storageContext->IndexElementCount = IndexElementCount;

    CopyMemory( 
        &storageContext->TemplateFormat, 
        &fileHeader.TemplateFormat, 
        sizeof(WINBIO_UUID)
        );

    storageContext->Version = fileHeader.Version;

    CopyMemory(
        &storageContext->DatabaseId,
        DatabaseId,
        sizeof(WINBIO_UUID)
        );

    wcsncpy_s(
        storageContext->FilePath,
        MAX_PATH+1,
        FilePath,
        MAX_PATH
        );

    // TODO: Copy other values as necessary to the storage context (not shown).

cleanup:

    if (FAILED(hr))
    {
        _CleanupCryptoContext(&storageContext->CryptoContext);

        if (fileOpen)
        {
            CloseHandle(fileHandle);
            fileHandle = INVALID_HANDLE_VALUE;
        }
    }

    // Call the SecureZeroMemory function to overwrite the template encryption key 
    // on the stack.
    SecureZeroMemory( &protectedData, sizeof(struct _MY_ADAPTER_DPAPI_DATA));

    return hr;
}

要件

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

こちらもご覧ください

プラグイン関数

StorageAdapterCloseDatabase

StorageAdapterEraseDatabase

StorageAdapterOpenDatabase

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

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

フィードバック

その他のリソース