HttpWPXFilterProc Function

Article
08/13/2010

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:

Syntax

DWORD WINAPI HttpWPXFilterProc(
  __in  PHTTP_FILTER_CONTEXT pfc,
  __in  DWORD NotificationType,
  __in  VOID* pvNotification
);

Parameters

pfc
Pointer to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP session.
NotificationType
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
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
SF_NOTIFY_FORWARD_RAW_DATA	HTTP_FILTER_RAW_DATA
SF_NOTIFY_RECEIVE_RESPONSE_HEADERS	WPX_FILTER_PREPROC_HEADERS
SF_NOTIFY_RECEIVE_RESPONSE_RAW_DATA	HTTP_FILTER_RAW_DATA
SF_NOTIFY_ROUTING	WPX_FILTER_ROUTE

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.

SF_STATUS_REQ_NEXT_NOTIFICATION
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.
SF_STATUS_REQ_FINISHED
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.
SF_STATUS_REQ_FINISHED_KEEP_CONN
Treated the same as SF_STATUS_REQ_FINISHED.
SF_STATUS_REQ_HANDLED_NOTIFICATION
This filter handled the notification. No other handlers should be called for this specific notification, and the next notification will be called.
SF_STATUS_REQ_ERROR
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.

Note

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.
SF_STATUS_REQ_READ_NEXT
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.

Remarks

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).

Requirements

Server	Requires Windows Server 2008 R2 or Windows Server 2008 x64 Edition with SP2.
Version	Requires Forefront Threat Management Gateway (TMG) 2010.
Header	Declared in Wpxhttpfilt.h.

Share via