PIBIO_STORAGE_CREATE_DATABASE_FN callback function (winbio_adapter.h)
Called by the Windows Biometric Framework to create and configure a new database.
Syntax
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
)
{...}
Parameters
[in, out] Pipeline
Pointer to a WINBIO_PIPELINE structure associated with the biometric unit performing the operation.
[in] DatabaseId
Pointer to a GUID that uniquely identifies the database. This is the same GUID used to register the database in the registry.
[in] Factor
A WINBIO_BIOMETRIC_TYPE value that specifies the type of the biometric factor stored in this database. Only WINBIO_TYPE_FINGERPRINT is currently supported.
[in] Format
Pointer to a GUID that specifies the vendor-defined format of the data in the VendorDataBlock member of the WINBIO_BIR object.
[in] FilePath
Pointer to a NULL-terminated Unicode string that contains the fully qualified file path for the database.
[in] ConnectString
Pointer to a NULL-terminated Unicode connection string for the database.
[in] IndexElementCount
The number of elements in the index vector. This can be equal to or greater than zero.
[in] InitialSize
A value that contains the beginning size of the database, in bytes.
Return value
If the function succeeds, it returns S_OK. If the function fails, it must return one of the following HRESULT values to indicate the error.
| Return code | Description |
|---|---|
|
A mandatory pointer argument is NULL. |
|
The StorageContext member of the pipeline object is NULL. |
Remarks
The biometric service calls this method if the StorageAdapterOpenDatabase function fails and if an AutoCreate flag has been associated with the database in the registry.
If this function succeeds, the database must be left in the open state. The Windows Biometric Framework will not issue a subsequent call to this function.
Examples
The following pseudocode shows one possible implementation of this function. The example does not compile. You must adapt it to suit your purpose.
/////////////////////////////////////////////////////////////////////////////////////////
//
// 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;
}
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 7 [desktop apps only] |
| Minimum supported server | Windows Server 2008 R2 [desktop apps only] |
| Target Platform | Windows |
| Header | winbio_adapter.h (include Winbio_adapter.h) |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for