GetServerVariable Function

Artikel
06/16/2017

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.

Dela via