Share via

Event Notifications

  • Article

The following are alphabetical lists of the event notifications that may be sent by the Forefront TMG Web proxy to a Web filter. Only event notifications of the types that a Web filter registers to receive from the Forefront TMG Web proxy are sent to it. These notifications include standard notifications that are available in Internet Information Services (IIS) for ISAPI filters and notifications that are specific to Forefront TMG. For more information about event notifications, including the typical order in which they are sent, see Introduction to Web Filters.

Notifications Specific to Forefront TMG

The following flags specify the event notifications introduced for the notifications that are specific to Forefront TMG. The Forefront TMG Web proxy sends these event notifications only to a Web filter whose implementation of the GetWPXFilterVersion entry-point function registers the Web filter to receive them by including the applicable flags in the bitmask contained in the dwFlags member of the HTTP_FILTER_VERSION data structure that is passed by a pointer in the pVer parameter of this entry-point function. The Forefront TMG Web proxy sends these event notifications to a Web filter by calling its implementation of the HttpWPXFilterProc entry-point function and specifying the applicable flag in the NotificationType parameter to indicate the type of event notification that is being sent.

  • SF_NOTIFY_FORWARD_RAW_DATA
    A notification specific to Forefront TMG. Sent before raw data is transmitted to the Web server. May be used by filters that want to modify this data. Provided with the HTTP_FILTER_RAW_DATA notification structure, which contains a pointer to the data to be transmitted.

  • SF_NOTIFY_FORWARD_RAW_DATA_COMPLETED
    A notification specific to Forefront TMG. Sent when the transmission of raw data to the Web server is complete. Provided without a notification-specific structure, the pointer to which contains a NULL value. May be used by filters that want to modify the data based on the complete content.

  • SF_NOTIFY_POLICY_CHECK_COMPLETED
    A notification specific to Forefront TMG. Sent after the Forefront TMG policy check has been completed, and the request has either been allowed or denied. After this notification has been received, the Web filter can request the GUID of the policy rule that either allowed or denied the request. The filter can also request additional data from the client (SF_STATUS_REQ_READ_NEXT), although the read operation will fail if all of the data has already been received.

  • SF_NOTIFY_RECEIVE_RESPONSE_HEADERS
    A notification specific to Forefront TMG. Sent after the response headers have been received. May be used by Web filters to modify the headers received from the Web server before the response is processed by Forefront TMG. Provided with the WPX_FILTER_PREPROC_HEADERS notification structure, which contains pointers to functions that can be used to retrieve and modify the headers or portions of the response.

    Note  This notification may be sent more than once for a single client POST request. The notification is provided each time that a Web server returns an HTTP status 100 (Continue) response, and once more for the final response.

  • SF_NOTIFY_RECEIVE_RESPONSE_RAW_DATA
    A notification specific to Forefront TMG. Sent after data is received from the Web server or upstream proxy server (but not from the Forefront TMG cache), and before it is processed by Forefront TMG. May be used by a Web filter to modify the content of the response received from the Web server. If caching is enabled, the response is cached after it is modified. Provided with the HTTP_FILTER_RAW_DATA notification structure, which contains a pointer to the response received from the Web server.

    Note  More than one response header may be sent for a single client POST request. If the data is parsed, take into account the possibility of multiple response headers.

    If a filter accumulates a response in an SF_NOTIFY_RECEIVE_RESPONSE_RAW_DATA notification without releasing it to the next filter, the filter may not release the data until it receives an SF_NOTIFY_END_OF_REQUEST notification, which indicates that the server closed the connection. At this point, the filter will typically call WriteClient with the accumulated data. However, this will prevent other server-side filters from obtaining the raw response data, and those filters will be skipped. We recommend not accumulating the body of a response without releasing it to the next filter. If you must do so, accumulate the data in an SF_NOTIFY_SEND_RAW_DATA notification rather than an SF_NOTIFY_RECEIVE_RESPONSE_RAW_DATA notification.

  • SF_NOTIFY_ROUTING
    A notification specific to Forefront TMG. Sent before the Web filter forwards a request to the destination server. Can be used by a filter to override the host name, IP address, or port for the connection. Provided with the WPX_FILTER_ROUTE notification structure, which contains the destination host name or IP address and port.

    Note  If the request is routed either to another Forefront TMG computer within the array or to an upstream proxy server and a connection to the server cannot be established, the server will be marked as down, another route to the destination will be calculated if possible, and an attempt will be made to connect to a different server. This process will be repeated three times before failing the request, and an SF_NOTIFY_ROUTING notification will be sent before each attempt to establish a connection.

General Notifications

The following flags specify the event notifications that are not specific to Forefront TMG, but are supported by it. The Forefront TMG Web proxy sends these event notifications only to a Web filter whose implementation of the GetFilterVersion entry-point function registers the Web filter to receive them by including the applicable flags in the bitmask contained in the dwFlags member of the HTTP_FILTER_VERSION data structure that is passed by a pointer in the pVer parameter of this entry-point function. The Forefront TMG Web proxy sends these event notifications to a Web filter by calling its implementation of the HttpFilterProc entry-point function and specifying the applicable flag in the NotificationType parameter to indicate the type of event notification that is being sent.

  • SF_NOTIFY_ACCESS_DENIED
    Sent just after Forefront TMG determines that access is denied for the requested resource, but before Forefront TMG sends a response to the client. Provided with the HTTP_FILTER_ACCESS_DENIED notification structure.

  • SF_NOTIFY_AUTH_COMPLETE
    Sent just after Forefront TMG determines that access is allowed to the requested resource in a forward or reverse proxy scenario with HTTP authentication. Provided with the HTTP_FILTER_AUTH_COMPLETE_INFO or WPX_HTTP_FILTER_AUTH_COMPLETE_INFO notification structure.

    In an array with two or more members, this notification is sent only on the first array member that receives the Web request. It is not sent on an array member to which the request is redirected by the Cache Array Routing Protocol (CARP) algorithm. Authentication is performed only on the first array member that receives the request.

  • SF_NOTIFY_AUTHENTICATION
    Sent just before Forefront TMG attempts to authenticate the client. Can be used to provide a custom authentication scheme. Provided with the HTTP_FILTER_AUTHENT or WPX_FILTER_AUTHENT_EX notification structure, which contains the client's credentials. If authentication is not required by any rule, the notification is sent with an anonymous user.

    In an array with two or more members, this notification is sent only on the first array member that receives the Web request. It is not sent on an array member to which the request is redirected by the Cache Array Routing Protocol (CARP) algorithm. Authentication is performed only on the first array member that receives the request.

  • SF_NOTIFY_END_OF_NET_SESSION
    Sent when a network session with a client is ending. Provided without a notification-specific structure, the pointer to which contains a NULL value.

  • SF_NOTIFY_END_OF_REQUEST
    Sent when the end of a request is detected. Provided without a notification-specific structure, the pointer to which contains a NULL value.

  • SF_NOTIFY_FLAG_LARGE_SIZE_AWARE
    Sent when support for large files (greater than 4GB) is required. Web Proxy filters that want to handle large files must declare themselves as "large size aware". Filters that do not do this are considered legacy filters that don't support large files. Provided with the WPX_FILTER_LOG notification structure.

  • SF_NOTIFY_LOG
    Sent after the end of a request is detected, just before Forefront TMG writes the session to the Forefront TMG log. Provided with the HTTP_FILTER_LOG notification structure, which contains the information that will be written to the log.

  • SF_NOTIFY_PREPROC_HEADERS
    Sent when the Forefront TMG Web proxy finishes preprocessing the headers in a request. May be used by filters to modify the headers before the Web proxy begins to process the information in them. Provided with the HTTP_FILTER_PREPROC_HEADERS notification structure, which contains pointers to functions that can retrieve and modify the headers or portions of the request.

  • SF_NOTIFY_READ_RAW_DATA
    Sent when data is read from the client. May be sent more than once for a single request. Provided with the HTTP_FILTER_RAW_DATA notification structure, which contains a pointer to the data read.

  • SF_NOTIFY_SEND_RAW_DATA
    Sent when Forefront TMG is about to send raw data back, including data retrieved from the cache, to the client or downstream proxy server. May be sent more than once for a single request.

    Note  More than one response header may be sent for a single client POST request. If the data is parsed, take into account the possibility of multiple response headers.

    Provided with the HTTP_FILTER_RAW_DATA notification structure, which contains a pointer to the data being sent.

    If the Web filter modifies data retrieved from the cache before sending it to the client, the data stored in the cache is not modified.

  • SF_NOTIFY_SEND_RESPONSE
    Sent after the request is processed, but before any headers are sent back to the client. This notification is not used when Forefront TMG returns a response from the Web server or from the cache. However, it is called when a filter generates a response by using SF_REQ_SEND_RESPONSE_HEADER (), or when the Web proxy generates a response, such as an error page.

    Provided with the HTTP_FILTER_SEND_RESPONSE notification structure, which contains pointers to functions that can be used to retrieve and modify the headers or portions of the response.

  • SF_NOTIFY_URL_MAP
    Sent after a URL is translated to a physical path on the Web server. This notification is irrelevant for the Forefront TMG Web proxy because it does not have any physical URLs. However, it is provided as it was in Microsoft Proxy Server 2.0 for compatibility with earlier versions.

    Provided with the HTTP_FILTER_URL_MAP notification structure.

Port Security Flags

In addition to the flags for types of event notifications, flags relating to the port security of connections are passed to the Forefront TMG Web proxy.

  • SF_NOTIFY_SECURE_PORT
    Notify the Web filter only for connections through a secure port.

  • SF_NOTIFY_NONSECURE_PORT
    Notify the Web filter only for connections through a nonsecure port.

These flags are used only in the bitmask set in the dwFlags member of the HTTP_FILTER_VERSION structure pointed to by the GetFilterVersion and GetWPXFilterVersion entry-point functions. The Web proxy does not include these flags in the bitmask passed in the NotificationType parameter of the HttpFilterProc and HttpWPXFilterProc entry-point functions.

These flags are set independently in calls to GetFilterVersion and GetWPXFilterVersion.

In GetFilterVersion these flags indicate the port security of the connections on which the event notifications that are not specific to Forefront TMG are sent, while in GetWPXFilterVersion these flags indicate the port security of the connections on which the event notifications specific to Forefront TMG are sent.

Setting both flags and not setting either flag result in the same behavior. The Web proxy sends notifications for both secure and nonsecure connections.

Send comments about this topic to Microsoft

Build date: 6/30/2010