GetServerVariable Function
Collapse the table of content
Expand the table of content

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:
© 2016 Microsoft