HttpFilterProc callback function

Applies to: desktop apps only

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

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

Minimum supported client

None supported

Minimum supported server

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

Version

Forefront Threat Management Gateway (TMG) 2010

Header

Httpfilt.h

See also

Entry-Point Functions

 

 

Build date: 7/12/2010