WinBioFree function (winbio.h)

Article
02/22/2024

Releases memory allocated for the client application by an earlier call to a Windows Biometric Framework API function. Starting with Windows 10, build 1607, this function is available to use with a mobile image.

Syntax

HRESULT WinBioFree(
  [in] PVOID Address
);

Parameters

[in] Address

Address of the memory block to delete.

Return value

If the function succeeds, it returns S_OK. If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

Return code	Description
E_POINTER	The Address parameter cannot be NULL.

Remarks

Multiple functions in the Windows Biometric Framework API allocate memory for the client application and pass the address of that memory to the client. To prevent memory leaks, you must call WinBioFree to delete the block when you are done using the information it contains. You delete the memory by passing its address to WinBioFree. You can find the address by de-referencing the pointer specified by the appropriate parameter in each of the following functions.

Function	Parameter	Type of block allocated
WinBioCaptureSample	Sample	Structure
WinBioEnumBiometricUnits	UnitSchemaArray	Array of structures
WinBioEnumDatabases	StorageSchemaArray	Array of structures
WinBioEnumEnrollments	SubFactorArray	Array of integers
WinBioEnumServiceProviders	BspSchemaArray	Array of structures
EventCallBack	Event	Structure
CaptureCallback	Sample	Structure

Examples

The following function calls WinBioEnumBiometricUnits to enumerate the installed biometric sensors, and it calls WinBioFree to release the memory created by WinBioEnumBiometricUnits. Link to the Winbio.lib static library and include the following header files:

Windows.h
Stdio.h
Conio.h
Winbio.h

HRESULT EnumerateSensors( )
{
    HRESULT hr = S_OK;
    PWINBIO_UNIT_SCHEMA unitSchema = NULL;
    SIZE_T unitCount = 0;

    // Enumerate the installed biometric units.
    hr = WinBioEnumBiometricUnits( 
            WINBIO_TYPE_FINGERPRINT,        // Type of biometric unit
            &unitSchema,                    // Array of unit schemas
            &unitCount );                   // Count of unit schemas

    if (FAILED(hr))
    {
        wprintf_s(L"\nWinBioEnumBiometricUnits failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

e_Exit:

    // Free memory.
    if (unitSchema != NULL)
    {
        WinBioFree(unitSchema);
        unitSchema = NULL;
    }

    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.h (include Winbio.h)
Library	Winbio.lib
DLL	Winbio.dll