GetServerVariable callback function

Article
08/27/2012

Applies to: desktop apps only

The GetServerVariable callback function retrieves information about the server and the current 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 about the types of event notifications that are sent to Web filters, see Event Notifications.

The GetServerVariable callback function is declared as:

Syntax

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

Parameters

pfc [in]
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 [in]
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 Forefront TMG are presented in this table, along with a description of the information that is retrieved when the variable is specified.
lpvBuffer [out]
Pointer to a buffer for receiving the requested information.
lpdwSizeofBuffer [in, out]
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 value

This callback function returns TRUE if the call is successful; otherwise, it returns FALSE. To obtain extended error information, call GetLastError, which may return one of the following Windows system error codes:

ERROR_INVALID_PARAMETER
The value specified in either the lpszVariableName or lpdwSizeofBuffer parameter is invalid.
ERROR_INVALID_INDEX
The variable identifier specified is invalid or unsupported.
ERROR_INSUFFICIENT_BUFFER
The buffer pointed to by the lpvBuffer parameter is not large enough to contain the information requested. The required buffer size is stored in *lpdwSizeofBuffer after the call.
ERROR_NO_DATA
The information 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
A string indicating 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 value retrieved for the AUTH_TYPE variable is meaningless.
AUTH_USER
The user name used for authentication.

CERT_CONTEXT
A pointer to the CERT_CONTEXT structure of the client certificate. 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_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
A bitmask containing 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. A text value that must be converted to a numeric value is retrieved. 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_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.
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_URI
The URL requested.
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_CARP_ENABLED
A string containing 0 (false) or 1 (true). If true, the Web listener at which the request arrived is configured to attempt to retrieve the requested object from the cache of the current array using the Cache Array Routing Protocol (CARP) algorithm. If false, the Web listener is configured to retrieve the requested object from the site specified in the URL. For a request that has been redirected by the CARP algorithm, the value retrieved depends on the CARP setting of the listener for the network in which the request was redirected, not on the CARP setting of the listener on which the original request was received from the Web browser or downstream proxy server. For example, the value retrieved for a request received on the Internal network with CARP enabled will be true. If the request is redirected by CARP to another array member through a dedicated network for intra-array communication with CARP disabled, the value retrieved on the second array member will be false.
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_INTRA_ARRAY_TRAFFIC
A string containing 0 (false) or 1 (true). The value retrieved is always false for requests that have not been redirected by the Cache Array Routing Protocol (CARP) algorithm. For example, the value retrieved is false if the CARP algorithm is not enabled, or if the server is the first array member to receive the request. The value retrieved is true for a request that is redirected to the server from another array member by the CARP algorithm after the intra-array authentication request in the same session.
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.
IS_SERVER_SIDE_GENERATED_REQUEST
A string containing 0 (false) or 1 (true). If true, the request was generated by the Authentication Delegation Filter.
LISTENER_GUID
The GUID of the Web listener for the current session.
LOCAL_ADDR
A string containing the local IP address.
LOGON_USER
The user name used for authentication.
QUERY_STRING
Not supported in Forefront TMG; 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. The string will contain INTRA_ARRAY if the request is to be sent to another array member using the Cache Array Routing Protocol (CARP) algorithm.
SCRIPT_NAME
Not supported in Forefront TMG; w3proxy.dll is always retrieved.
SELECTED_RULE_GUID
The GUID of the selected policy rule. This variable is not available on an array member to which the request is redirected by the Cache Array Routing Protocol (CARP) algorithm. The policy rules are checked only on the first array member that receives the request.
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-Forefront TMG/4.0.
URL
The URL requested (after the request has been parsed). This value is also returned for HTTP_PROXY_URI.
USER_CACHING_KEY
The user caching key as set by the SetUserCachingKey function.
WEB_ROUTING_RULE
The routing rule's GUID.

Requirements

Minimum supported client	None supported
Minimum supported server	Windows Server 2008 R2, Windows Server 2008 with SP2 (64-bit only)
Version	Forefront Threat Management Gateway (TMG) 2010
Header	Wpxhttpfilt.h