PIBIO_STORAGE_CREATE_DATABASE_FN função de retorno de chamada (winbio_adapter.h)
Chamado pela Estrutura Biométrica do Windows para criar e configurar um novo banco de dados.
Sintaxe
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
)
{...}
Parâmetros
[in, out] Pipeline
Ponteiro para uma estrutura WINBIO_PIPELINE associada à unidade biométrica que executa a operação.
[in] DatabaseId
Ponteiro para um GUID que identifica exclusivamente o banco de dados. Esse é o mesmo GUID usado para registrar o banco de dados no registro.
[in] Factor
Um valor WINBIO_BIOMETRIC_TYPE que especifica o tipo do fator biométrico armazenado neste banco de dados. Somente WINBIO_TYPE_FINGERPRINT tem suporte no momento.
[in] Format
Ponteiro para um GUID que especifica o formato definido pelo fornecedor dos dados no membro VendorDataBlock do objeto WINBIO_BIR .
[in] FilePath
Ponteiro para uma cadeia de caracteres Unicode terminada em NULL que contém o caminho de arquivo totalmente qualificado para o banco de dados.
[in] ConnectString
Ponteiro para uma cadeia de conexão Unicode terminada em NULL para o banco de dados.
[in] IndexElementCount
O número de elementos no vetor de índice. Isso pode ser igual ou maior que zero.
[in] InitialSize
Um valor que contém o tamanho inicial do banco de dados, em bytes.
Retornar valor
Se a função for bem-sucedida, ela retornará S_OK. Se a função falhar, ela deverá retornar um dos seguintes valores HRESULT para indicar o erro.
| Código de retorno | Descrição |
|---|---|
|
Um argumento de ponteiro obrigatório é NULL. |
|
O membro StorageContext do objeto de pipeline é NULL. |
Comentários
O serviço biométrico chamará esse método se a função StorageAdapterOpenDatabase falhar e se um sinalizador AutoCreate tiver sido associado ao banco de dados no registro.
Se essa função for bem-sucedida, o banco de dados deverá ser deixado no estado aberto. A Estrutura Biométrica do Windows não emitirá uma chamada subsequente para essa função.
Exemplos
O pseudocódigo a seguir mostra uma implementação possível dessa função. O exemplo não é compilado. Você deve adaptá-lo para se adequar ao seu propósito.
/////////////////////////////////////////////////////////////////////////////////////////
//
// 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;
}
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 7 [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 R2 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | winbio_adapter.h (inclua Winbio_adapter.h) |