SF_REQ_SEND_RESPONSE_HEADER Callback Function

The SF_REQ_SEND_RESPONSE_HEADER form of the ServerSupportFunction callback function can be used to request that the Forefront TMG Web proxy send a complete HTTP response header to the client browser, including the HTTP status, server version, and message time. Your filter can also, optionally, append other header information to the end of a header generated by the Web proxy, such as a Content-Type or Content-Length header.

Syntax

BOOL WINAPI * ServerSupportFunction(
  __in  struct _HTTP_FILTER_CONTEXT* pfc,
  __in  enum SF_REQ_TYPE sfReq,
  __in  PVOID pData,
  __in  DWORD ul1,
		DWORD ul2
);

Parameters

pfc

Pointer to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP session. Pass the filter context in this parameter.

sfReq

Specifies the particular support function that is to be executed by the Forefront TMG Web filter, in this case, SF_REQ_SEND_RESPONSE_HEADER.

pData

Points to a null-terminated string that contains an HTTP status string, such as 401 Access Denied. If pData is set to NULL, the default response, 200 OK, will be sent in the response header.

ul1

Points to an optional null-terminated string that contains the headers to add. The string should be in the following format:

header1:value1\r\nheader2:value2\r\n\r\n

The string may contain one or more headers. Each header and value pair must be terminated by an extra "\r\n".

ul2

Unused in this support function.

Return Value

This callback function returns TRUE if the call is successful; otherwise, it returns FALSE. To obtain extended error information, call GetLastError.

Remarks

If you append your own headers to the server-generated headers, you must terminate the header string with an extra carriage return and linefeed.

This support function can be called only once for each HTTP request.

After using this function, the filter should use WriteClient to send any other information, and then use the SF_STATUS_REQ_FINISHED return value to terminate the request.

A Web filter may cause a recursive call of itself or a simple call of another Web filter inside itself. This may occur if a Web filter sends a response by using either ServerSupportFunction (SF_REQ_SEND_RESPONSE_HEADER) or WriteClient.

Consider two cases:

The call was from a RAW_DATA notification, either READ_RAW_DATA or SEND_RAW_DATA.
The call was from any other notification (non-RAW_DATA).

After this function is used, all filters that are registered for the SF_NOTIFY_SEND_RESPONSE notification will receive that notification.

If the call was from a RAW_DATA notification, only filters with higher order than the filter that sent the response will be called in the SEND_RAW_DATA notification.

If the call was from any other notification, the filter that sent the response and the filters with higher order will be called in the SEND_RAW_DATA notification.

For example, suppose you have three filters: Filter_Low with low priority, Filter_Medium with medium priority, and Filter_High with high priority. Filter_Low and Filter_High subscribed to SEND_RESPONSE and SEND_RAW_DATA. Filter_Medium subscribed to SEND_RESPONSE and SEND_RAW_DATA as well, but also subscribed to another notification.

From its extra notification, Filter_Medium sends either ServerSupportFunction (SF_REQ_SEND_RESPONSE_HEADER) or WriteClient.

Forefront TMG will call the filters before the ServerSupportFunction (SF_REQ_SEND_RESPONSE_HEADER) or WriteClient complete, as follows:

If ServerSupportFunction (SF_REQ_SEND_RESPONSE_HEADER) or WriteClient is sent from a raw data notification, only Filter_High will receive the SF_NOTIFY_SEND_RAW_DATA notification.
If ServerSupportFunction (SF_REQ_SEND_RESPONSE_HEADER) or WriteClient is sent from a non-raw data notification, both Filter_Medium and Filter_High will receive SF_NOTIFY_SEND_RAW_DATA, but Filter_Low will not receive the SF_NOTIFY_SEND_RAW_DATA notification.
If ServerSupportFunction (SF_REQ_SEND_RESPONSE_HEADER) is sent from any notification, all filters that subscribed to SF_NOTIFY_SEND_RESPONSE will receive the SF_NOTIFY_SEND_RESPONSE notification, including Filter_Low.

For more information about the types of event notifications that are sent to Web filters, see Event Notifications.

Requirements

Server	Requires Windows Server 2008.
Version	Requires Forefront Threat Management Gateway (TMG).
Header	Declared in Wpxhttpfilt.h.
DLL	Requires W3Filter.dll.