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 );
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.
