Export (0) Print
Expand All

GetServerVariable Function

IIS 6.0

The GetServerVariable function retrieves information about an HTTP connection or about IIS itself.

Some server variables, such as Request_Method and Content_Length are embedded in the EXTENSION_CONTROL_BLOCK structure. You can use GetServerVariable to obtain information about the request or server that is not included in EXTENSION_CONTROL_BLOCK.

BOOL WINAPI GetServerVariable(
   HCONN hConn,
   LPSTR lpszVariableName,
   LPVOID lpvBuffer,
   LPDWORD lpdwSizeofBuffer
);

hConn

Specifies the connection handle.

lpszVariableName

A null-terminated string that indicates which server variable is requested.

lpvBuffer

Points to the buffer to receive the requested information.

lpdwSizeofBuffer

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.

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.

The GetServerVariable function copies information into a buffer supplied by the caller. The information can include CGI variables and information relating to an HTTP connection or to the server itself.

The lpszVariableName can be used to retrieve a specific request (client) header by using the HTTP_headername value. For example, supplying the value HTTP_ACCEPT returns the Accept header, and HTTP_VERSION returns the Version header.

Unicode Server Variables

It is possible to retrieve server variable values as unicode values by prepending "UNICODE_" to the name of the server variable. For example, following example shows you how to use the C++ programming language to retrieve the value of the "SERVER_NAME" server variable as a unicode string and store it in the buffer specified by szUrlW. Note that GetServerVariable treats data as a buffer and not characters. For example, cbUrlW contains the number of bytes occupied by the Unicode string, not the number of characters:

#define BUF_LEN 100 

WCHAR szUrlW[BUF_LEN]; 
DWORD cbUrlW = BUF_LEN * sizeof(WCHAR); 

pECB->GetServerVariable( pECB->ConnID, 
                         "UNICODE_SERVER_NAME", 
                         szUrlW, 
                         &cbUrlW ); 

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

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 httpext.h.

Show:
© 2014 Microsoft