Event Notifications

Microsoft Internet Security and Acceleration Server 2004/2006 SDK

Event Notifications

The following are alphabetical lists of the event notifications that may be sent by the ISA Server Web proxy to a Web filter. Only event notifications of the types that a Web filter registers to receive from the ISA Server Web proxy are sent to it. For more information about event notifications, including the typical order in which they are sent, see Introduction to Web Filters.

Notifications Specific to ISA Server 2006 and ISA Server 2004

The following flags specify the event notifications introduced in ISA Server 2004. The ISA Server 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 ISA Server 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 ISA Server 2006 and ISA Server 2004. 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 ISA Server 2006 and ISA Server 2004. 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 ISA Server 2006 and ISA Server 2004. Sent after the ISA Server 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 ISA Server 2006 and ISA Server 2004. 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 ISA Server. 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 ISA Server 2006 and ISA Server 2004. Sent after data is received from the Web server or upstream proxy server (but not from the ISA Server cache), and before it is processed by ISA Server. 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 ISA Server 2006 and ISA Server 2004. 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 ISA Server 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 ISA Server 2006 and ISA Server 2004, but are supported by it. The ISA Server 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 ISA Server 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 ISA Server determines that access is denied for the requested resource, but before ISA Server sends a response to the client. Provided with the HTTP_FILTER_ACCESS_DENIED notification structure.

SF_NOTIFY_AUTH_COMPLETE

Sent just after ISA Server 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 Enterprise Edition, 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 ISA Server 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.

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_LOG

Sent after the end of a request is detected, just before ISA Server writes the session to the ISA Server 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 ISA Server 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 ISA Server 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 ISA Server 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 ISA Server 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 ISA Server 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 ISA Server 2006 and ISA Server 2004 are sent, while in GetWPXFilterVersion these flags indicate the port security of the connections on which the event notifications specific to ISA Server 2006 and ISA Server 2004 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.