GetServerVariable Function
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
);
Parameters
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.
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
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".
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 httpext.h.