GetWPXFilterVersion function

Article
08/27/2012

Applies to: desktop apps only

The GetWPXFilterVersion function is called by the Forefront TMG Web proxy after the GetFilterVersion function (if it is implemented) to let a Web filter register for the event notifications that are specific to Forefront TMG. In the call, the Web proxy passes a pointer to an HTTP_FILTER_VERSION data structure, which the Web filter can use to supply key filter configuration information to the Web proxy. The information passed to the Web proxy includes the version number of the Web filter API used by the Web filter and a bitmask containing the flags that specify which event notifications the Web filter can process. This function must be implemented together with HttpWPXFilterProc.

To register for the event notifications that are available to ISAPI filters in Internet Information Services (IIS), use GetFilterVersion. For more information about the types of event notifications that are sent to Web filters, see Event Notifications.

The declaration of the GetWPXFilterVersion function is:

Syntax

BOOL WINAPI GetWPXFilterVersion(
  _Inout_  PHTTP_FILTER_VERSION pVer
);

Parameters

pVer [in, out]
Pointer to an HTTP_FILTER_VERSION structure that contains a member which specifies the version information supplied by the Forefront TMG Web proxy and members which the Web filter uses to supply the version number of its Web filter API and a bitmask containing flags that specify the event notifications to be sent to it. The description field is not used in Forefront TMG.

The bitmask may include flags for the following event notifications that are specific to Forefront TMG:
- SF_NOTIFY_FORWARD_RAW_DATA
- SF_NOTIFY_FORWARD_RAW_DATA_COMPLETED
- SF_NOTIFY_POLICY_CHECK_COMPLETED
- SF_NOTIFY_RECEIVE_RESPONSE_HEADERS
- SF_NOTIFY_RECEIVE_RESPONSE_RAW_DATA
- SF_NOTIFY_ROUTING
In addition to the flags for types of event notifications, flags relating to the port security of connections may be included in the bitmask:
- SF_NOTIFY_SECURE_PORT
- SF_NOTIFY_NONSECURE_PORT
Note The bitmask should not include the SF_NOTIFY_ORDER_LOW, SF_NOTIFY_ORDER_MEDIUM, and SF_NOTIFY_ORDER_HIGH flags that are used to set the priority of ISAPI extensions (filters). For a Web filter, the priority is specified by the Priority property of the FPCWebFilter object that represents the filter. This property is initially set in the call to the Add method of the FPCWebFilters collection that creates the FPCWebFilter object in the filter registration code.

Return value

If this function returns TRUE, the filter will remain loaded. If the function returns FALSE, the filter functionality will be terminated and the filter will be unloaded. If the function returns FALSE in your filter, the filter must call SetLastError with an error code that indicates the nature of the failure.

Note It is important to register only for those notifications that are necessary for your filter's purposes. Registering for additional notifications will reduce performance.

Remarks

At a minimum, a Web filter must implement either GetFilterVersion and HttpFilterProc, or GetWPXFilterVersion and HttpWPXFilterProc (or both pairs of functions).

Requirements

Minimum supported client	None supported
Minimum supported server	Windows Server 2008 R2, Windows Server 2008 with SP2 (64-bit only)
Version	Forefront Threat Management Gateway (TMG) 2010
Header	Wpxhttpfilt.h