GetHeader Callback Function

The GetHeader callback function retrieves an HTTP header. The function retrieves a header for an incoming request after an SF_NOTIFY_PREPROC_HEADERS or SF_NOTIFY_AUTH_COMPLETE notification, for an incoming response after an SF_NOTIFY_RECEIVE_RESPONSE_HEADERS notification, and for an outgoing response after an SF_NOTIFY_SEND_RESPONSE notification. For more information about the types of event notifications that are sent to Web filters, see Event Notifications.

The GetHeader callback function is declared as:

Syntax

BOOL WINAPI * GetHeader(
  __in	 struct _HTTP_FILTER_CONTEXT* pfc,
  __in	 LPSTR lpszName,
  __out	LPVOID lpvBuffer,
  __inout  LPDWORD lpdwSize
);

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.

lpszName

Pointer to a null-terminated string containing the name of the header to retrieve. Header names should include the trailing colon (:). This parameter is not case-sensitive.

The special values "method", "url", "version", and "body" (for requests only) can be used to retrieve individual portions of the request line. When the value "body" is specified, the function retrieves the part of the body that has already been received.

The special value "status" can be used to retrieve the status from the response line.

Note that the special values do not include a trailing colon.

lpvBuffer

Pointer to a buffer of size lpdwSize for receiving the header requested. If there are multiple instances of the requested header, a semicolon-delimited series of all of the instances found is retrieved.

lpdwSize

Pointer to a DWORD that indicates the size of the buffer. This should be set to the size of the buffer specified in lpvBuffer, for example, "sizeof(achBuffer)". After the call, *lpdwSize contains the number of bytes retrieved including the null terminator. Therefore, for the retrieved string, it is equal to "strlen(lpvBuffer) + 1". If the function fails because the buffer is not large enough, *lpdwSize contains the size needed.

Return Value

This callback function returns TRUE if the call is successful; otherwise, it returns FALSE. To obtain extended error information, call GetLastError, which may return one of the following Windows system error codes:

ERROR_ARITHMETIC_OVERFLOW: The value of the calculated buffer size exceeded 32 bits.
ERROR_INSUFFICIENT_BUFFER: The buffer pointed to by the lpvBuffer parameter is not large enough to contain the header requested. The required buffer size is stored in *lpdwSize after the call.
ERROR_INVALID_INDEX: The header specified in the lpszName parameter was not found.
ERROR_INVALID_PARAMETER: The value specified in either the lpvBuffer or lpdwSize parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY: Not enough memory was available to complete the requested operation.
ERROR_NOT_SUPPORTED: The request is an HTTP 0.9 request, which contains no headers.

Remarks

A pointer to this function is included as a member of the following structures:

Requirements

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