GetHeader Callback Function

Article
08/13/2010

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 R2 or Windows Server 2008 x64 Edition with SP2.
Version	Requires Forefront Threat Management Gateway (TMG) 2010.
Header	Declared in Wpxhttpfilt.h.
DLL	Requires W3Filter.dll.

Share via