HttpFilterProc Callback Function

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

Information about notifications is provided in Event Notifications.

The declaration of HttpFilterProc is:

Syntax

DWORD WINAPI HttpFilterProc(
  __in  PHTTP_FILTER_CONTEXT pfc,
  __in  DWORD NotificationType,
  __in  LPVOID 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_ACCESS_DENIED	HTTP_FILTER_ACCESS_DENIED
SF_NOTIFY_AUTH_COMPLETE	HTTP_FILTER_AUTH_COMPLETE_INFO or WPX_HTTP_FILTER_AUTH_COMPLETE_INFO
SF_NOTIFY_AUTHENTICATION	HTTP_FILTER_AUTHENT or WPX_FILTER_AUTHENT_EX
SF_NOTIFY_LOG	HTTP_FILTER_LOG
SF_NOTIFY_PREPROC_HEADERS	HTTP_FILTER_PREPROC_HEADERS or WPX_FILTER_PREPROC_HEADERS
SF_NOTIFY_READ_RAW_DATA	HTTP_FILTER_RAW_DATA
SF_NOTIFY_SEND_RAW_DATA	HTTP_FILTER_RAW_DATA
SF_NOTIFY_SEND_RESPONSE	HTTP_FILTER_SEND_RESPONSE
SF_NOTIFY_URL_MAP	HTTP_FILTER_URL_MAP

Note The SF_NOTIFY_END_OF_NET_SESSION and SF_NOTIFY_END_OF_REQUEST event notifications do not have corresponding structures. 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 notifications.

SF_STATUS_REQ_FINISHED_KEEP_CONN

Treated the same as SF_STATUS_REQ_FINISHED.

SF_STATUS_REQ_HANDLED_NOTIFICATION

The filter handled the notification. No other event 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 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 the 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 individual 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.
Version	Requires Forefront Threat Management Gateway (TMG).
Header	Declared in Httpfilt.h.