Edit

WFP Version-Independent Names and Targeting Specific Versions of Windows

  • Article

In many cases, the Windows Filtering Platform (WFP) API provides more than one version of a function or structure.

Most data and function names in the WFP API end with a version number, such as "0" or "1", even if there is only one version.

Version Mapping in fwpvi.h

The fwpvi.h header file is included starting with the Windows 7 SDK and WDK. This header file maps the versionless API name to the version that is appropriate for use with a given operating system.

For example, here is a brief excerpt from the version of fwpvi.h included in the Windows 8 SDK.

#define FwpmNetEventCreateEnumHandle FwpmNetEventCreateEnumHandle0
#if (NTDDI_VERSION >= NTDDI_WIN8)
#define FwpmNetEventEnum FwpmNetEventEnum2
#elif (NTDDI_VERSION >= NTDDI_WIN7)
#define FwpmNetEventEnum FwpmNetEventEnum1
#else
#define FwpmNetEventEnum FwpmNetEventEnum0
#endif

As shown above, there is only one version of FwpmNetEventCreateEnumHandle – FwpmNetEventCreateEnumHandle0 – so any call to FwpmNetEventCreateEnumHandle will always call FwpmNetEventCreateEnumHandle0, regardless of the operating system targeted.

However, there are three versions of of FwpmNetEventEnum: FwpmNetEventEnum0, FwpmNetEventEnum1, and FwpmNetEventEnum2. The fwpvi.h header file ensures that a call to FwpmNetEventEnum will call the version most appropriate to the targeted operating system:

Calling Version-Independent Functions and Structures

WFP developers targeting a particular operating system or WDK version are encouraged to always program against the version-independent macros. This will automatically select the latest version supported in the operating system you are targeting. Use of the most recent header files is recommended, even when targeting an earlier operating system. Doing this consistently will ensure the latest supported version is used, and can also make it easier to maintain and update your code.

The WFP API reference documentation describes each version of a numbered API. If more than one version exists, the targeted operating system is noted. However, developers will generally want to call the version-independent (numberless) APIs, and indicate the targeted operating system (such as NTDDI_WIN6 for Windows Vista or NTDDI_WIN8 for Windows 8).

To ensure proper handling of functions that take different parameters in different versions, you can include conditional blocks such as #if (NTDDI_VERSION >= NTDDI_WIN7).