GetServerVariable

The GetServerVariable function retrieves information about a connection or about the IIS itself.

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

Parameters

hConn

[in] Specifies the connection handle.

lpszVariableName

[in] A null-terminated string that indicates which variable is requested. These are the possible variables.

ALL_HTTP	Retrieves all HTTP headers that were received. These variables are of the form HTTP_<header field name>. The headers consist of a null-terminated string with the individual headers separated by line feeds.
ALL_RAW	Retrieves all headers in the raw-form. The header-names and values appear as they are sent by the client. Currently, this value is primarily used by Proxy server and other similar applications.
APPL_MD_PATH	Retrieves the metabase path of the application for the ISAPI DLL or the script.
APPL_PHYSICAL_PATH	Retrieves the physical path that corresponds with the metabase path. IIS maps the namespace to the physical directory path ; this allows APPL_MD_PATH to return this value. This is a costly function (in run time) compared to getting just APPL_MD_PATH.
AUTH_PASSWORD	Specifies the value entered in the client's authentication dialog. This variable is only available if Basic authentication is used.
AUTH_TYPE	Specifies the type of authentication used. If the string is empty, then no authentication is used. Possible values are kerberos, user, SSL/PCT, Basic, and NTLM.
AUTH_USER	Specifies the value entered in the client's authentication dialog.
CERT_COOKIE	Specifies a unique ID for a client certificate. Returned as a string. Can be used as a signature for the whole client certificate.
CERT_FLAGS	If bit0 is set to 1, a client certificate is present. If bit1 is set to 1, the Certifying Authority of the client certificate is invalid (not on this server's list of recognized CAs).
CERT_ISSUER	Specifies the issuer field of the client certificate. For example, the following codes might be O=MS, OU=IAS, CN=user name, C=USA, and so on.
CERT_KEYSIZE	Specifies the number of bits in the Secure Sockets Layer (SSL) connection key size.
CERT_SECRETKEYSIZE	Specifies the number of bits in the server certificate private key.
CERT_SERIALNUMBER	Specifies the serial number field of the client certificate.
CERT_SERVER_ISSUER	Specifies the issuer field of the server certificate.
CERT_SERVER_SUBJECT	Specifies the subject field of the server certificate.
CERT_SUBJECT	Specifies the subject field of the client certificate.
CONTENT_LENGTH	Specifies the number of bytes of data which the script or extension can expect to receive from the client. This total does not include headers.
CONTENT_TYPE	Specifies the content type of the information supplied in the body of a POST request.
HTTP_ACCEPT	Specifies the special-case HTTP header.
HTTPS	Returns on if the request came in through secure channel (SSL), or off if the request is for a non-secure channel.
HTTPS_KEYSIZE	Specifies the number of bits in the SSL connection key size.
HTTPS_SECRETKEYSIZE	Specifies the number of bits in server certificate private key.
HTTPS_SERVER_ISSUER	Specifies the issuer field of the server certificate.
HTTPS_SERVER_SUBJECT	Specifies the subject field of the server certificate.
INSTANCE_ID	Specifies the ID for the IIS instance in textual format. If the instance ID is 1, it appears as a string. This value can be used to retrieve the ID of the Web-server instance, in the metabase, to which the request belongs.
INSTANCE_META_PATH	Specifies the metabase path for the instance to which the request belongs.
PATH_INFO	Specifies the additional path information, as given by the client. This consists of the trailing part of the URL after the script name, but before the query string, if any.
PATH_TRANSLATED	Specifies this is the value of PATH_INFO, but with any virtual path expanded into a directory specification.
QUERY_STRING	Specifies the information which follows the question mark in the URL that referenced this script.
REMOTE_ADDR	Specifies the IP address of the client or agent of the client (for example gateway, proxy, or firewall) that sent the request.
REMOTE_HOST	Specifies the host name of the client or agent of the client (for example, gateway, proxy or firewall) that sent the request.
REMOTE_USER	Specifies the user name supplied by the client and authenticated by the server. This comes back as an empty string when the user is anonymous.
REQUEST_METHOD	Specifies the HTTP request method verb.
SCRIPT_NAME	Specifies the name of the script program being executed.
SERVER_NAME	Specifies the server's host name, or IP address, as it should appear in self-referencing URLs.
SERVER_PORT	Specifies the TCP/IP port on which the request was received.
SERVER_PORT_SECURE	Specifies a string of either 0 or 1. If the request is being handled on the secure port, then this will be 1. Otherwise, it will be 0.
SERVER_PROTOCOL	Specifies the name and version of the information retrieval protocol relating to this request.
SERVER_SOFTWARE	Specifies the name and version of the Web server under which the ISAPI Extension DLL program is running.
URL	Specifies the base portion of the URL. Parameter values will not be included. The value is determined when IIS parses the URL from the header.

lpvBuffer

[out] Points to the buffer to receive the requested information.

lpdwSizeofBuffer

[in/out] 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.

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.

Note In respect to AUTH_TYPE, if the string is not empty it does not mean the user was authenticated (if the authentication scheme is not basic or NTLM). The server allows authentication schemes it does not natively understand since an ISAPI Filter may be able to handle that particular scheme.

The lpszVariableName can be used to retrieve a specific 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.

The values of the fields for the HTTP_ACCEPT variable are concatenated, and separated by a comma (,).

If bit 1 of the Cert_Flags variable is set to 1, indicating that the certificate is invalid, IIS 4.0 will reject the certificate. Earlier versions of IIS will not reject the certificate.

© 1997 by Microsoft Corporation. All rights reserved.