функция обратного вызова PIBIO_STORAGE_CREATE_DATABASE_FN (winbio_adapter.h)

Вызывается платформой Биометрических данных 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

Указатель на GUID, указывающий определенный поставщиком формат данных в элементе VendorDataBlock объекта WINBIO_BIR .

[in] FilePath

Указатель на строку Юникода, завершающуюся null, которая содержит полный путь к файлу для базы данных.

[in] ConnectString

Указатель на строка подключения Юникода с завершением NULL для базы данных.

[in] IndexElementCount

Количество элементов в векторе индекса. Это значение может быть равно нулю или больше нуля.

[in] InitialSize

Значение типа , содержащее начальный размер базы данных в байтах.

Возвращаемое значение

Если функция завершается успешно, она возвращает S_OK. Если функция завершается сбоем, она должна вернуть одно из следующих значений HRESULT , чтобы указать на ошибку.

Код возврата	Описание
E_POINTER	Обязательный аргумент указателя — NULL.
WINBIO_E_INVALID_DEVICE_STATE	Элемент StorageContext объекта конвейера имеет значение NULL.

Комментарии

Биометрическая служба вызывает этот метод, если функция StorageAdapterOpenDatabase завершается сбоем и если с базой данных в реестре связан флаг автосоздание .

Если эта функция выполняется успешно, база данных должна быть оставлена в открытом состоянии. Windows Biometric Framework не будет выполнять последующий вызов этой функции.

Примеры

В следующем псевдокоде показана одна из возможных реализаций этой функции. Пример не компилируется. Вы должны адаптировать его в соответствии с вашей целью.

/////////////////////////////////////////////////////////////////////////////////////////
//
// 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
Header	winbio_adapter.h (включая Winbio_adapter.h)

См. также раздел

Функции подключаемого модуля

StorageAdapterCloseDatabase

StorageAdapterEraseDatabase

StorageAdapterOpenDatabase