FBWF API
5/10/2007
The File-Based Write Filter (FBWF) application programming interface (API) exposes a set of functions that allow 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 entire physical media volumes. FBWF, however, also supports write-through for individual files or directories. Write-through permits the application to specify specific files and directories that the FBWF should not protect, thus 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 all writes modify only the cached file. The individual file cache may be further managed with the FbwfCommitFile and FbwfRestoreFile functions.
The FBWF API functions enable applications to specify and query system wide settings as well as 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 an entire 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:), or a device name (e.g., \Device\Harddiskvolume).
File-Based Write Filter Sessions
Since the File-Based Write Filter cannot be enabled while the system is running, the FBWF makes a distinction between the current session (since the last system boot) and the next session (after the next system boot).
Applications call FBWF API functions during the current session to enable and configure the FBWF for the next session.
Some FBWF API functions allow configuration information to be queried for either the current FBWF session, or the next (following the next system boot).
Applications must call FbwfEnableFilter before calling 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 ensure that you understand the expected behavior.
- Exceeding the cache threshold causes some disk operations to fail. It is important that applications manage their available cache. Win32 API calls will generally return ERROR_HANDLE_DISK_FULL in this case.