SF_REQ_SEND_RESPONSE_HEADER callback function

Article
08/27/2012

Applies to: desktop apps only

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 [in]
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 [in]
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 [in]
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 [in]
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

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	Wpxhttpfilt.h