FBWF API (Standard 7 SP1)
7/8/2014
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 with 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 File-Based Write Filter 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 is a globally unique identifier (GUID) that identifies the volume (for example, \\?\Volume{26a21bda-a627-11d7-9931-806e6f6e6963}\).
The ability to reference a volume using a volume GUID path is new to Windows Embedded Standard 7. Referencing volumes using GUIDs is more reliable because you avoid factors that make it difficult to identify a volume. For example, two volumes having the same label, a volume having no drive letter or label, and drive letters changing 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 File-Based Write Filter 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 shows 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.