FBWF API (Standard 8)
7/8/2014
Review the structures and functions provided by the File-Based Write Filter API in Windows Embedded 8 Standard (Standard 8).
The File-Based Write Filter (FBWF) API exposes a set of functions that enable an application to interact with the FBWF.
To enable support for the FBWF API, add the FBWF API to your component by linking to Fbwflib.lib.
FBWF can be used to protect whole physical media volumes. However, FBWF also supports write-through for individual files or directories. Write-through lets applications specify files and directories that the FBWF should not protect, therefore giving applications more flexibility. When an application tries to write to a protected file, a copy of that file is created in cache memory, and write operations modify only the cached file. The individual file cache may be additionally managed by using the FbwfCommitFile and FbwfRestoreFile functions.
The FBWF API functions enable applications to specify and query system-wide settings and cache settings for individually protected volumes and files. The following list shows the typical usage scenarios for these functions:
- Disabling/enabling File-Based Write Filtering
- Setting/querying cache memory usage
- Setting/querying compression usage
- Enable/disable write filtering for a whole volume
- Excluding a file or directory from write filtering
- Committing/restoring cache contents to or from the actual file
Volume Names in the File-Based Write Filter
The FBWF implements volume level write-protection. Therefore, many of the File-Based Write Filter API functions take a volume name as an input parameter.
The volume name can be either a drive letter (for example, C), a device name (for example, \Device\Harddiskvolume), or a volume GUID path in the form of "\\?\Volume{<GUID>}\" where <GUID> identifies the volume (for example, \\?\Volume{26a21bda-a627-11d7-9931-806e6f6e6963}\).
Referencing volumes by using GUIDs is more reliable because you avoid factors that make it difficult to identify a volume. For example, two volumes may have the same label, a volume might not have a drive letter or label, and drive letters change as volumes are added to and removed from the computer. For more information, see Naming a Volume. To retrieve the GUID volume path for a volume, see the GetVolumeNameForVolumeMountPoint Function.
File-Based Write Filter Sessions
Because the FBWF cannot be enabled while the system is running, the FBWF differentiates between the current session (since the last system restart) and the next session (after the next system restart).
Applications call FBWF API functions during the current session to enable and configure the FBWF for the next session.
Some FBWF API functions enable configuration information to be queried for either the current FBWF session, or the next, following the next system restart.
Applications must call FbwfEnableFilter before they call other FBWF configuration functions.
FBWF API Considerations
The following list provides information that is important to consider before you use the API:
- Many of the FBWF functions do not take effect until the system restarts. Review the function documentation to make sure that you understand the expected behavior.
- Exceeding the cache threshold causes some disk operations to fail. Make sure that applications manage their available cache. Win32 API calls generally return ERROR_HANDLE_DISK_FULL in this case.
FWF API Header and Library Files
On a default installation of the Standard 8 Toolkit, the FBWF API header and library files are installed in the following locations:
- C:\Program Files (x86)\Windows Embedded 8 Standard\Developer Content\SDK\inc\fbwfapi.h
- C:\Program Files (x86)\Windows Embedded 8 Standard\Developer Content\SDK\x86\Write Filter\fbwfapi.lib
- C:\Program Files (x86)\Windows Embedded 8 Standard\Developer Content\SDK\amd64\Write Filter\fbwfapi.lib