GetFilterVersion Callback Function

The GetFilterVersion function (if it is implemented) is the first entry-point function called by the Forefront TMG Web proxy to let a Web filter register for event notifications that are available to ISAPI filters in Internet Information Services (IIS). 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 flags that specify which event notifications the Web filter can process. This function must be implemented together with HttpFilterProc.

To register for the notifications that are specific to Forefront TMG, use GetWPXFilterVersion. For more information about the types of event notifications that are sent to Web filters, see Event Notifications.

The declaratation of the GetFilterVersion function is:

Syntax

BOOL WINAPI GetFilterVersion(
  __inout  PHTTP_FILTER_VERSION pVer
);

Parameters

pVer

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 available to ISAPI filters in IIS:

SF_NOTIFY_ACCESS_DENIED
SF_NOTIFY_AUTH_COMPLETE
SF_NOTIFY_AUTHENTICATION
SF_NOTIFY_END_OF_NET_SESSION
SF_NOTIFY_END_OF_REQUEST
SF_NOTIFY_LOG
SF_NOTIFY_PREPROC_HEADERS
SF_NOTIFY_READ_RAW_DATA
SF_NOTIFY_SEND_RAW_DATA
SF_NOTIFY_SEND_RESPONSE
SF_NOTIFY_URL_MAP

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

Server	Requires Windows Server 2008.
Version	Requires Forefront Threat Management Gateway (TMG).
Header	Declared in Httpfilt.h.