GetHeader callback function

  • Article

Applies to: desktop apps only

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 [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.

  • lpszName [in]
    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 [out]
    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 [in, out]
    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

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

See also

Callback Functions

 

 

Build date: 7/12/2010