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:
BOOL WINAPI * GetServerVariable( __in struct _HTTP_FILTER_CONTEXT* pfc, __in LPSTR lpszVariableName, __out LPVOID lpvBuffer, __inout LPDWORD lpdwSizeofBuffer );
Pointer to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP session. Pass the filter context in this parameter.
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.
Pointer to a buffer for receiving the requested information.
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.
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:
The value specified in either the lpszVariableName or lpdwSizeofBuffer parameter is invalid.
The variable identifier specified is invalid or unsupported.
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.
The information requested is not available.
The following are possible values for the lpszVariableName parameter.
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 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.
The password that is used for Basic authentication.
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.
The user name used for authentication.
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) {
...
}
A unique identifier (ID) for a client certificate. Retrieved as a string. Can be used as a signature for the entire client certificate.
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.
The issuer field of the client certificate. For example, the codes might be O=MS, OU=IAS, CN=user name, or C=USA.
The number of bits in the SSL connection key size.
The number of bits in the server certificate private key.
The serial-number field of the client certificate.
The issuer field of the server certificate.
The subject field of the server certificate.
The subject field of the client certificate.
The value of the request content length header, or 0 if it does not exist.
The content type of the information supplied in the body of a request.
The default domain for authentication of the listener for the current session.
The current Web filter's GUID.
Returns CGI/1.1.
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.
The URL requested.
The Web proxy realm for Basic and Digest authentication.
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.
The value stored in the client certificate CertProperty property.
The number of bits in the SSL connection key size.
The number of bits in the server certificate private key.
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.
The issuer field of the server certificate.
The subject field of the server certificate.
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.
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.
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.
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.
A string containing TRUE or FALSE, indicating if the request is a forward proxy or reverse proxy request.
A string containing 0 (false) or 1 (true). If true, the request was generated by the Authentication Delegation Filter.
The GUID of the Web listener for the current session.
A string containing the local IP address.
The user name used for authentication.
Not supported in Forefront TMG; the value retrieved is always an empty string.
The IP address of the client or agent of the client (for example gateway, proxy, or firewall) that sent the request.
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.
The port of the client or agent of the client (for example, gateway, proxy, or firewall) that sent the request.
The user name supplied by the client and authenticated by the server. An empty string is retrieved when the user is anonymous.
The HTTP request method verb.
A value of 0 (false) or 1 (true), indicating if the request is a forward proxy or reverse proxy request.
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.
Not supported in Forefront TMG; w3proxy.dll is always retrieved.
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.
The value stored in the server certificate CertProperty property.
The value stored in the server certificate CertProperty property.
The server's host name, or IP address, as it should appear in self-referencing URLs.
The TCP/IP port on which the request was received.
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.
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.
The name and version of the information retrieval protocol relating to the request.
A string containing Microsoft-Forefront TMG/4.0.
The URL requested (after the request has been parsed). This value is also returned for HTTP_PROXY_URI.
The user caching key as set by the SetUserCachingKey function.
The routing rule's GUID.
| Server | Requires Windows Server 2008. |
|---|---|
| Version | Requires Forefront Threat Management Gateway (TMG). |
| Header |
Declared in Wpxhttpfilt.h. |
| DLL |
Requires W3Filter.dll. |
Send comments about this topic to Microsoft
Build date: 11/30/2009
© 2008 Microsoft Corporation. All rights reserved.