GetServerVariable Function (filters)

  • Article

The GetServerVariable callback function specifies a server variable that the ISAPI filter needs to retrieve from IIS.

BOOL WINAPI GetServerVariable(
      PHTTP_FILTER_CONTEXT pfc,
      LPSTR lpszVariableName,
      LPVOID lpvBuffer,
      LPDWORD lpdwSize
);

Parameters

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

  • lpszVariableName
    Points to a string that contains the variable to retrieve.

  • lpvBuffer
    Points to the buffer to receive the requested information.

  • lpdwSize
    Points to a DWORD that indicates the size of the buffer pointed to by lpvBuffer. On successful completion, the DWORD contains the size of bytes transferred into the buffer, including the null-terminating byte.

Return Values

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. The Win32? GetLastError function can be used to determine why the call failed. The following are the possible error values.

Return code

Description

ERROR_INVALID_PARAMETER

Bad connection handle, or invalid values, in either lpszVariableName or lpdwSizeOfBuffer.

ERROR_INVALID_INDEX

Bad or unsupported variable identifier.

ERROR_INSUFFICIENT_BUFFER

Buffer too small. The required buffer size is *lpdwSizeofBuffer.

ERROR_NO_DATA

The data requested is not available.

Remarks

Unicode Server Variables

It is possible to retrieve server variable values as unicode values by prepending "UNICODE_" to the name of the server variable.

It is not possible to retrieve unicode representations of request headers that are retrieved using the "HTTP_" or "HEADER_" prefix. For example, "UNICODE_HTTP_ACCEPT" is not a valid server variable name, but "HTTP_ACCEPT" and "HEADER_ACCEPT" are valid names to retrieve the request's Accept header, if it exists.

It is possible to retrieve request headers with a "-" (dash) as well as "_" (underscore) by using the "HEADER_" prefix. This is an improvement over the "HTTP_" prefix, which was unable to retrieve headers with an '_' (underscore). i.e. If you had a request with the following two headers:

  • My_Header: Value1

  • My-Header: Value2

Using "HTTP_MY_HEADER" as the name, you will only retrieve "Value2". Meanwhile, using "HEADER_MY_HEADER" will get "Value1", and "HEADER_MY-HEADER" will get "Value2".

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.

See Also