HttpWPXFilterProc function

Applies to: desktop apps only

The HttpWPXFilterProc function is called by the Forefront TMG Web proxy whenever an event for which the filter has registered in GetWPXFilterVersion occurs. The Web proxy uses this function to pass information and control to the Web filter. This function must be implemented together with GetWPXFilterVersion.

Information about notifications is provided in Event Notifications.

The declaration of HttpWPXFilterProc is:


  _In_  DWORD NotificationType,
  _In_  VOID *pvNotification


  • pfc [in]
    Pointer to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP session.

  • NotificationType [in]
    Flag that indicates the type of event notification that is being processed. For more information about the types of event notifications that are sent using this function, see Event Notifications.

  • pvNotification [in]
    Pointer to the notification-specific structure that contains more information about the current context of the request. You should cast this pointer to a pointer to the relevant notification structure according to the notification type, which is listed in the following table. For more information about the types of event notifications that are sent to Web filters, see Event Notifications.

    Notification type Notification structure


    Note  The SF_NOTIFY_FORWARD_RAW_DATA_COMPLETED notification does not have a corresponding structure. The pointer will contain a NULL value.

Return value

Implementations of this function may return the following values to indicate how the event was handled.

    The next filter in the notification chain should be called. Typically, unless your filter specifically needs to return one of the other values, it should return this value.

    The filter handled the HTTP request. The server should disconnect the session.

    Note  After this value is returned, the filter will continue to receive notifications. At a minimum, the filter will receive SF_NOTIFY_END_OF_REQUEST and SF_NOTIFY_END_OF_NET_SESSION.

    Treated the same as SF_STATUS_REQ_FINISHED.

    This filter handled the notification. No other handlers should be called for this specific notification, and the next notification will be called.

    An error occurred. The HTTP request will be aborted when this status is returned. If no data has been sent, the server will send an error message to the client. The filter should call SetLastError with the nature of the failure before returning this value.


    If a filter does not set the last error, the last error will be the error currently associated with the current thread. You can use GetLastError to see its value. If the last error is 0 or ERROR_IO_PENDING, Forefront TMG will treat the error as ERROR_INTERNAL_ERROR.

    After the SF_STATUS_REQ_ERROR value is returned, the filter will continue to receive notifications.

    If SetLastError is used with ERROR_ACCESS_DENIED, it causes the Web proxy to return a 405 Access Denied response. Otherwise, it will return a 50x response.

    The complete request has not yet been received from the client or the Web server. The Web proxy should issue another read and notify the filter with the additional data.

    SF_STATUS_REQ_READ_NEXT can only be returned for SF_NOTIFY_RECEIVE_RESPONSE_HEADERS notifications (for a response), or for SF_NOTIFY_READ_RAW_DATA and SF_NOTIFY_POLICY_CHECK_COMPLETED notifications (for a request). Also, it cannot be used for a request after the first SF_NOTIFY_FORWARD_RAW_DATA notification, that is, after the Web proxy has sent some data to the Web server.

    Higher priority filters will only receive the additional data, whereas the filter that returns this value will receive both the initial data and the additional data.


This function usually serves as the dispatch for a Web filter. Separate functions are often created to serve as handlers for the separate notifications, especially if the handling code is complicated.

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


Minimum supported client

None supported

Minimum supported server

Windows Server 2008 R2, Windows Server 2008 with SP2 (64-bit only)


Forefront Threat Management Gateway (TMG) 2010



See also

Entry-Point Functions



Build date: 7/12/2010