次の方法で共有


GetServerVariable callback function

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

See also

Callback Functions

 

 

Build date: 7/12/2010