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 的指標，指定WINBIO_BIR 物件之 VendorDataBlock 成員中數據廠商定義的格式。
[in] FilePath
NULL 終止 Unicode 字串的指標，其中包含資料庫的完整檔案路徑。
[in] ConnectString
資料庫的 NULL 終止 Unicode 連接字串 指標。
[in] IndexElementCount
索引向量中的項目數。 這可以等於或大於零。
[in] InitialSize
值，包含資料庫的開頭大小，以位元組為單位。
傳回值
如果函式成功，則會傳回S_OK。 如果函式失敗，它必須傳回下列其中一個 HRESULT 值，以指出錯誤。
| 傳回碼 | Description |
|---|---|
|
強制指標自變數為 NULL。 |
|
管線物件的 StorageContext 成員為 NULL。 |
備註
如果 StorageAdapterOpenDatabase 函式失敗，而且 AutoCreate 旗標已與登錄中的資料庫相關聯，生物特徵辨識服務就會呼叫這個方法。
如果此函式成功，資料庫必須保持開啟狀態。 Windows 生物特徵辨識架構不會發出此函式的後續呼叫。
範例
下列虛擬程式代碼顯示此函式的一個可能實作。 此範例不會編譯。 您必須調整它以符合您的用途。
/////////////////////////////////////////////////////////////////////////////////////////
//
// 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) |