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.

See Also

Entry-Point Functions


Send comments about this topic to Microsoft

Build date: 11/30/2009

© 2008 Microsoft Corporation. All rights reserved.