PIBIO_STORAGE_CREATE_DATABASE_FN fungsi panggilan balik (winbio_adapter.h)
Dipanggil oleh Windows Biometric Framework untuk membuat dan mengonfigurasi database baru.
Sintaks
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
)
{...}
Parameter
[in, out] Pipeline
Penunjuk ke struktur WINBIO_PIPELINE yang terkait dengan unit biometrik yang melakukan operasi.
[in] DatabaseId
Penunjuk ke GUID yang secara unik mengidentifikasi database. Ini adalah GUID yang sama yang digunakan untuk mendaftarkan database di registri.
[in] Factor
Nilai WINBIO_BIOMETRIC_TYPE yang menentukan jenis faktor biometrik yang disimpan dalam database ini. Hanya WINBIO_TYPE_FINGERPRINT yang saat ini didukung.
[in] Format
Penunjuk ke GUID yang menentukan format data yang ditentukan vendor di anggota VendorDataBlock dari objek WINBIO_BIR .
[in] FilePath
Penunjuk ke string Unicode yang dihentikan NULL yang berisi jalur file yang sepenuhnya memenuhi syarat untuk database.
[in] ConnectString
Penunjuk ke string koneksi Unicode yang dihentikan NULL untuk database.
[in] IndexElementCount
Jumlah elemen dalam vektor indeks. Ini bisa sama dengan atau lebih besar dari nol.
[in] InitialSize
Nilai yang berisi ukuran awal database, dalam byte.
Nilai kembali
Jika fungsi berhasil, fungsi akan mengembalikan S_OK. Jika fungsi gagal, fungsi harus mengembalikan salah satu nilai HRESULT berikut untuk menunjukkan kesalahan.
| Menampilkan kode | Deskripsi |
|---|---|
|
Argumen pointer wajib adalah NULL. |
|
Anggota StorageContext dari objek alur adalah NULL. |
Keterangan
Layanan biometrik memanggil metode ini jika fungsi StorageAdapterOpenDatabase gagal dan jika bendera AutoCreate telah dikaitkan dengan database dalam registri.
Jika fungsi ini berhasil, database harus dibiarkan dalam status terbuka. Windows Biometric Framework tidak akan mengeluarkan panggilan berikutnya ke fungsi ini.
Contoh
Pseudocode berikut menunjukkan salah satu kemungkinan implementasi fungsi ini. Contoh tidak dikompilasi. Kau harus menyesuaikannya sesuai dengan tujuanmu.
/////////////////////////////////////////////////////////////////////////////////////////
//
// 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;
}
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 7 [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2008 R2 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | winbio_adapter.h (termasuk Winbio_adapter.h) |