GetServerVariable Callback Function

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

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 Forefront TMG 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 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

Server Requires Windows Server 2008.
Version Requires Forefront Threat Management Gateway (TMG).
Header

Declared in Wpxhttpfilt.h.

DLL

Requires W3Filter.dll.

See Also

Callback Functions


Send comments about this topic to Microsoft

Build date: 11/30/2009

© 2008 Microsoft Corporation. All rights reserved.

[an error occurred while processing this directive]