Microsoft Internet Security and Acceleration Server 2004 SDK

GetServerVariable

The GetServerVariable callback function retrieves information about the server and this connection. For some notifications, some variables might not be defined. For example, the AUTH_TYPE variable might not be defined before an SF_NOTIFY_AUTHENTICATION notification. For more information on the types of event notifications that are sent to Web filters, see Event Notifications.

The GetServerVariable callback function is declared as:

BOOL WINAPI * GetServerVariable(
  struct _HTTP_FILTER_CONTEXT* pfc,
  LPSTR lpszVariableName,
  LPVOID lpvBuffer,
  LPDWORD lpdwSizeofBuffer
);

Parameters

pfc
Pointer to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP session. Pass the filter context in this parameter.
lpszVariableName
Pointer to a null-terminated string that indicates which variable is requested. The Remarks section lists possible variables. In addition to the listed variables, any system environment variable can be requested, and any HTTP header can be requested by adding HTTP_ to its name (such as HTTP_HOST). Variables supported by ISA Server 2004 are presented in this table, along with a description of the information that is retrieved when the variable is specified.
lpvBuffer
Pointer to a buffer for receiving the requested information.
lpdwSizeofBuffer
Pointer to a DWORD that indicates the size of the buffer pointed to by the lpvBuffer parameter. On successful completion, the DWORD contains the number of bytes transferred into the buffer, including the null-terminating byte. If the function fails because the buffer is not large enough, the DWORD contains the size needed.

Return Values

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. The GetLastError function can be used to determine why the call failed. The following are possible error values.

ERROR_INVALID_PARAMETER
Invalid values in either lpszVariableName or lpdwSizeofBuffer.
ERROR_INVALID_INDEX
Invalid 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 following are possible values for the lpszVariableName parameter.

ALL_HTTP
All HTTP headers that were received. These headers are of the form HTTP_header_field_name. The headers consist of a null-terminated string with the individual headers separated by line feeds. This value is invalid for SF_NOTIFY_ACCESS_DENIED, SF_NOTIFY_SEND_RESPONSE, SF_NOTIFY_END_OF_REQUEST, SF_NOTIFY_LOG , and SF_NOTIFY_END_OF_NET_SESSION notifications. In these cases, incorrect or partial data may be retrieved.
ALL_RAW
All headers in raw form. The header names and values appear as they are sent by the client. This value is invalid for SF_NOTIFY_ACCESS_DENIED, SF_NOTIFY_SEND_RESPONSE, SF_NOTIFY_END_OF_REQUEST, SF_NOTIFY_LOG , and SF_NOTIFY_END_OF_NET_SESSION notifications. In these cases, incorrect or partial data may be retrieved.
AUTH_PASSWORD
The password that is used for Basic authentication.
AUTH_TYPE
The type of authentication used. Possible values are Basic, Digest, Kerberos, NTLM, and RADIUS. An empty string indicates that no authentication is used. If authentication fails, the content of the AUTH_TYPE variable is meaningless.
AUTH_USER
The user name used for authentication.
CERT_COOKIE
A unique identifier (ID) for a client certificate. Retrieved as a string. Can be used as a signature for the entire client certificate.
CERT_FLAGS
Information about the client certificate. If bit 0 is set to 1, a client certificate is present. If bit 1 is set to 1, the certification authority (CA) of the client certificate is invalid; that is, it is not on this server's list of recognized CAs. This is a text value that must be converted to a numeric value. If the client connects using an SSL connection that does not require a client certificate, the value retrieved is an empty string.
CERT_ISSUER
The issuer field of the client certificate. For example, the codes might be O=MS, OU=IAS, CN=user name, or C=USA.
CERT_KEYSIZE
The number of bits in the SSL connection key size.
CERT_CONTEXT
A pointer to the client certificate CERT_CONTEXT structure. The following snippet demonstrates how to use this value.
PCERT_CONTEXT pCtxt = NULL;
DWORD dwSize = sizeof(PCERT_CONTEXT);
BOOL fOK = pfc->GetServerVariable(pfx, "CERT_CONTEXT", &pCtxt, &dwSize);
If (fOK == TRUE && pCtxt != NULL) {
	...
}

CERT_SECRETKEYSIZE
The number of bits in the server certificate private key.
CERT_SERIALNUMBER
The serial-number field of the client certificate.
CERT_SERVER_ISSUER
The issuer field of the server certificate.
CERT_SERVER_SUBJECT
The subject field of the server certificate.
CERT_SUBJECT
The subject field of the client certificate.
CONTENT_LENGTH
The value of the request content length header, or 0 if it does not exist.
CONTENT_TYPE
The content type of the information supplied in the body of a request.
DEFAULT_DOMAIN
The default domain for authentication of the listener for the current session.
FILTERS_GUID
The current Web filter's GUID.
GATEWAY_INTERFACE
Returns CGI/1.1.
LOGON_USER
The Windows account that the user is logged on to.
HTTP_HOST
The contents of the HTTP Host header. This value is invalid for SF_NOTIFY_ACCESS_DENIED, SF_NOTIFY_SEND_RESPONSE, SF_NOTIFY_END_OF_REQUEST, SF_NOTIFY_LOG , and SF_NOTIFY_END_OF_NET_SESSION notifications. In these cases, incorrect or partial data may be retrieved.
HTTP_PROXY_URL
The request URL.
HTTP_REQ_REALM
The Web proxy realm for Basic and Digest authentication.
HTTPS
A string containing On if the request came in through a secure channel (with SSL encryption), or Off if the request is for an unsecure channel.
HTTPS_##CertProperty
The value stored in the client certificate CertProperty property.
HTTPS_KEYSIZE
The number of bits in the SSL connection key size.
HTTPS_SECRETKEYSIZE
The number of bits in the server certificate private key.
HTTPS_SERVER
A string containing On if the server response came in through a secure channel (with SSL encryption), or Off if the response came in through an unsecure channel.
HTTPS_SERVER_ISSUER
The issuer field of the server certificate.
HTTPS_SERVER_SUBJECT
The subject field of the server certificate.
IS_FROM_CACHE
A string containing 0 (false) or 1 (true), indicating whether the response is provided from the cache. This value is invalid for SF_NOTIFY_END_OF_REQUEST and SF_NOTIFY_LOG notifications. In these cases, 0 is always retrieved.
IS_PROXY_ORIGINATED_RESPONSE
A string containing 0 (false) or 1 (true). If true, the response was created by the Web proxy. This includes responses such as error pages, Web Proxy Auto-Discovery responses, or script-generated responses.
IS_REVERSE_PROXY
A string containing TRUE or FALSE, indicating if the request is a forward proxy or reverse proxy request.
LISTENER_GUID
The GUID of the Web listener for the current session.
LOCAL_ADDR
A string containing the local IP address.
QUERY_STRING
Not supported in ISA Server; the value retrieved is always an empty string.
REMOTE_ADDR
The IP address of the client or agent of the client (for example gateway, proxy, or firewall) that sent the request.
REMOTE_HOST
The host name of the client or agent of the client (for example, gateway, proxy, or firewall) that sent the request if reverse Domain Name System (DNS) is enabled. Otherwise, this value is set to the IP address specified by REMOTE_ADDR.
REMOTE_PORT
The port of the client or agent of the client (for example, gateway, proxy, or firewall) that sent the request.
REMOTE_USER
The user name supplied by the client and authenticated by the server. An empty string is retrieved when the user is anonymous.
REQUEST_METHOD
The HTTP request method verb.
REVERSE_PROXY
A value of 0 (false) or 1 (true), indicating if the request is a forward proxy or reverse proxy request.
ROUTING
A string containing DIRECT, UPSTREAM, or REDIRECT, depending on the selected routing rule.
SCRIPT_NAME
Not supported in ISA Server; w3proxy.dll is always retrieved.
SELECTED_RULE_GUID
The GUID of the selected policy rule.
SERVER_##CertProperty
The value stored in the server certificate CertProperty property.
SERVER_HTTPS_##CertProperty
The value stored in the server certificate CertProperty property.
SERVER_NAME
The server's host name, or IP address, as it should appear in self-referencing URLs.
SERVER_PORT
The TCP/IP port on which the request was received.
SERVER_PORT_SECURE
A string containing either 0 or 1. If the request is being handled on the secure port, this will be 1. Otherwise, it will be 0.
SERVER_PORT_SECURE_SERVER
A string containing either 0 (false) or 1 (true). If the server-side request is being handled by the server on the secure port, this will be 1. Otherwise, it will be 0.
SERVER_PROTOCOL
The name and version of the information retrieval protocol relating to the request.
SERVER_SOFTWARE
A string containing Microsoft-ISA Server/4.0.
URL
The request URL (after the request has been parsed). HTTP_PROXY_URL will also return this value.
USER_CACHING_KEY
The user caching key as set by the SetUserCachingKey function.
WEB_ROUTING_RULE
The routing rule's GUID.

Requirements

Server: Requires Windows Server 2003 or Windows 2000.
Version: Requires Internet Security and Acceleration Server 2004.
Header: Declared in Wpxhttpfilt.h.

See Also

Callback Functions