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:
DWORD WINAPI HttpFilterProc( __in PHTTP_FILTER_CONTEXT pfc, __in DWORD NotificationType, __in LPVOID pvNotification );
Pointer to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP session.
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.
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_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_PREPROC_HEADERS||HTTP_FILTER_PREPROC_HEADERS or WPX_FILTER_PREPROC_HEADERS|
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.
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 notifications.
Treated the same as SF_STATUS_REQ_FINISHED.
The filter handled the notification. No other event 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 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 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.
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.
|Server||Requires Windows Server 2008.|
|Version||Requires Forefront Threat Management Gateway (TMG).|
Declared in Httpfilt.h.
Build date: 11/30/2009
© 2008 Microsoft Corporation. All rights reserved.