StorageAdapterOpenDatabase

StorageAdapterOpenDatabase function

Called by the Windows Biometric Framework to open a database.

Syntax


HRESULT WINAPI StorageAdapterOpenDatabase(
  _Inout_ PWINBIO_PIPELINE Pipeline,
  _In_    PWINBIO_UUID     DatabaseId,
  _In_    LPCWSTR          FilePath,
  _In_    LPCWSTR          ConnectString
);

Parameters

Pipeline [in, out]

Pointer to the WINBIO_PIPELINE structure associated with the biometric unit performing the operation.

DatabaseId [in]

Pointer to a GUID that uniquely identifies the database. This is the same GUID used to register the database in the registry.

FilePath [in]

Pointer to a NULL-terminated Unicode string that contains the fully qualified file path for the database.

ConnectString [in]

Pointer to a NULL-terminated Unicode connection string for the database.

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 codeDescription
E_POINTER

A mandatory pointer argument is NULL.

WINBIO_E_DATABASE_CANT_CREATE

The database cannot be created.

WINBIO_E_DATABASE_CANT_FIND

The specified database cannot be found.

WINBIO_E_DATABASE_LOCKED

The database is currently locked by another application and cannot be opened.

WINBIO_E_DATABASE_CANT_OPEN

An unspecified problem has caused the request to fail.

WINBIO_E_INVALID_DEVICE_STATE

The StorageContext member of the pipeline object is NULL.

 

Examples

The following pseudocode shows one possible implementation of this function. The example does not compile. You must adapt it to suit your purpose.


/////////////////////////////////////////////////////////////////////////////////////////
//
// StorageAdapterOpenDatabase
//
// Purpose:
//      Opens the 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.
//      FilePath      - Pointer to the database file path.
//      ConnectString - Pointer to the database connection string.
//
static HRESULT
WINAPI
StorageAdapterOpenDatabase(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_UUID DatabaseId,
    __in LPCWSTR FilePath,
    __in LPCWSTR ConnectString
    )
{
    HRESULT hr = S_OK;
    struct _MY_ADAPTER_FILE_HEADER fileHeader = {0};
    HANDLE fileHandle = INVALID_HANDLE_VALUE;
    BOOL fileOpen = FALSE;
    BOOL headerLocked = FALSE;
    struct _MY_ADAPTER_DPAPI_DATA protectedData = {0};

    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline)   ||
        !ARGUMENT_PRESENT(DatabaseId) ||
        !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 (_OpenDatabase) that opens the file for shared
    // READ/WRITE access. This function should also decrypt, read, and return 
    // the protected data area.
    hr = _OpenDatabase(
            DatabaseId,
            FilePath,
            FALSE,          // Shared READ/WRITE access
            &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;
    }

    // Call a custom function (_LockDatabase) to lock the database for reading.
    hr = _LockDatabase( fileHandle, FALSE);
    if (FAILED(hr))
    {
        hr = WINBIO_E_DATABASE_CANT_OPEN;
        goto cleanup;
    }
    headerLocked = TRUE;

    // Call a custom function (_ReadFileHeader) to read the file header.
    hr = _ReadFileHeader( fileHandle, &fileHeader );
    if (FAILED(hr))
    {
        hr = WINBIO_E_DATABASE_CANT_OPEN;
        goto cleanup;
    }

    // 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
    //      - Template format
    //      - File version number
    //      - Database ID 
    //      - Database file path
    storageContext->IndexElementCount = fileHeader.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
        );

cleanup:

    // Call the SecureZeroMemory function to overwrite the template encryption key 
    // on the stack.
    SecureZeroMemory( &protectedData, sizeof(struct _MY_ADAPTER_DPAPI_DATA));

    if (headerLocked == TRUE)
    {
        _UnlockDatabase( fileHandle );
    }

    if (FAILED(hr))
    {
        _CleanupCryptoContext(&storageContext->CryptoContext);

        if (fileOpen)
        {
            CloseHandle(fileHandle);
            fileHandle = INVALID_HANDLE_VALUE;
        }
    }
    else
    {
        Pipeline->StorageHandle = fileHandle;
        fileHandle = INVALID_HANDLE_VALUE;
    }

    return hr;
}


Requirements

Minimum supported client

Windows 7 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]

Header

Winbio_adapter.h (include Winbio_adapter.h)

See also

Plug-in Functions
StorageAdapterCloseDatabase
StorageAdapterCreateDatabase
StorageAdapterEraseDatabase

 

 

Show:
© 2016 Microsoft