GetHeader Function

  • Article

The GetHeader callback function retrieves a header from IIS.

BOOL WINAPI * GetHeader(
   PHTTP_FILTER_CONTEXT pfc,
   LPSTR lpszName,
   LPVOID lpvBuffer,
   LPDWORD lpdwSize
);

Parameters

  • pfc
    Points to the HTTP_FILTER_CONTEXT Structure that is associated with the current, active HTTP transaction.

  • lpszName
    Points to the name of the header to retrieve. "URL" will return the raw URL.

  • lpvBuffer
    Points to a buffer of size lpdwSize where the value of the header will be stored. This should be set to the size of the buffer lpvBuffer, for example, sizeof( achBuffer). After the call, it contains the number of bytes retrieved including the null terminator. Therefore, for retrieved strings it is equal to strlen( lpvBuffer)+1.

  • lpdwSize
    The size of the buffer.

Return Values

If true, the function was successful. The lpvBuffer buffer is guaranteed to contain a string in a DWORD the size of lpvBuffer (including the terminating NULL character).

If false, the function failed. Nothing is assumed about the lpvBuffer buffer nor the DWORD. The GetLastError function indicates the reason for failure. The most common reasons are as follows:

Return code

Description

ERROR_INVALID_INDEX

The requested a header does not exist. On IIS 5.1 and earlier, this error is also returned if the header name did not end with a colon (:).

ERROR_INVALID_PARAMETER

The lpvBuffer pointer or the DWORD it points to is NULL. On IIS 6.0, this error is also returned if the header name did not end with a colon (:).

ERROR_INSUFFICIENT_BUFFER

The lpvBuffer buffer is too small. When this error is returned, lpvBuffer will be set to the size of the buffer required. It is common for people to call this function with a buffer of size zero, so that they can determine the needed size and call the function again. However, it is recommended to make the initial call with a properly sized buffer, so that you only need to allocate from the heap in exception cases.

Remarks

Header names should include the trailing colon (:). The special values method, URL, and version can be used to retrieve the individual portions of the request line. The special values must not include the trailing colon.

The special values "method", "url", and "version" can be used in SF_NOTIFY_PREPROC_HEADERS or SF_NOTIFY_AUTH_COMPLETE to retrieve the individual portions of the request line. The special value "status" can be used in SF_NOTIFY_SEND_RESPONSE to retrieve the entire response line. The special values must not include the trailing colon and should be lower-case.

Requirements

Client: Requires Windows XP Professional, Windows 2000 Professional, or Windows NT Workstation 4.0.

Server: Requires Windows Server 2003, Windows 2000 Server, or Windows NT Server 4.0.

Product: IIS

Header: Declared in httpfilt.h.