Event Notification Order

Typical Event Notification Sequence

In general, the events that occur during the processing of a typical IIS request and response are regular and predictable. The following list outlines the most common ordering of events:

1. SF_NOTIFY_READ_RAW_DATA: When a client sends a request, IIS will send SF_NOTIFY_READ_RAW_DATA, initially, only once. Data will be read until the client has sent all the HTTP headers associated with the request. If there is more data available from the client (such as in a POST operation), it will not be read until step 6.
2. SF_NOTIFY_PREPROC_HEADERS: A single SF_NOTIFY_PREPROC_HEADERS notification will occur for each request. This notification indicates that the server has completed pre-processing of the headers associated with the request, but has not yet begun to process the information contained within the headers.
3. SF_NOTIFY_URL_MAP: An SF_NOTIFY_URL_MAP notification will occur after the server has converted the virtual URL path contained in the HTTP request into a physical path on the server. Note that this event may occur several times for the same request.
4. SF_NOTIFY_AUTHENTICATION: An SF_NOTIFY_AUTHENTICATION notification occurs just before IIS attempts to authenticate the client. This notification will occur only on the first request made in a particular session, if Keep-Alives are actively being used by both server and client. If Keep-Alives are not in use, each request will cause IIS to send notification of this event.
5. SF_NOTIFY_ACCESS_DENIED: This event occurs if IIS has denied the client access to the requested resource (returning an HTTP 401 status code).
6. SF_NOTIFY_READ_RAW_DATA: As mentioned in step 1, if the client has more data to send, one or more SF_NOTIFY_READ_RAW_DATA notifications will occur here. Each read event notification will indicate that IIS has read another chunk equal in size to either the value of the UploadReadAheadSize metabase property (in kilobytes; usually 48 KB); or the remaining number of bytes available, if on the last chunk.

   Important   Additional raw read events are not always completely predictable, because many factors can force IIS to adopt a different chunking scheme. Therefore, your ISAPI filter should not rely on the exact behavior described here.

7. At this point in the request, IIS will begin to process the substance of the request. This may be done by an ISAPI extension, a CGI application, a script engine (such as ASP, PERL, and so on), or by IIS itself for static files.
8. SF_NOTIFY_SEND_RESPONSE: The SF_NOTIFY_SEND_RESPONSE event occurs after the request is processed and before headers are sent back to the client.
9. SF_NOTIFY_SEND_RAW_DATA: As the request handler returns data to the client, one or more SF_NOTIFY_SEND_RAW_DATA notifications will occur.
10. SF_NOTIFY_END_OF_REQUEST: At the end of each request, the SF_NOTIFY_END_OF_REQUEST notification occurs.
11. SF_NOTIFY_LOG: After the HTTP request has been completed, the SF_NOTIFY_LOG notification occurs just before IIS writes the request to the IIS log.
12. SF_NOTIFY_END_OF_NET_SESSION: When the connection between the client and server is closed, the SF_NOTIFY_END_OF_NET_SESSION notification occurs. If a Keep-Alive has been negotiated, it is possible that many HTTP requests occur before this notification occurs.

Exceptions to the Event Sequence

The preceding sequence is accurate enough for most purposes. However, it must be understood that there are often factors that can change the order of events. IIS or ISAPI filters may interrupt or modify the sequence of event notifications.

Important   Due to the complex and dynamic event model used by IIS, it is important that you do not rely on the exact event notification sequence described above. Your ISAPI filter must be prepared to deal with events that occur in a non-standard order, without failing and, more importantly, without causing IIS to fail.

Here are some of those situations in which the order or context of a event notification is nonstandard:

• If your ISAPI filter returns SF_STATUS_REQ_FINISHED from an SF_NOTIFY_PREPROC_HEADERS handler, SF_NOTIFY_URL_MAP will not be called for that request, although some subsequent notifications, such as SF_NOTIFY_END_OF_NET_SESSION, will still be called.
• If access has been denied the client for the request resource, the next event after SF_NOTIFY_ACCESS_DENIED will be SF_NOTIFY_END_OF_REQUEST.
• The SF_NOTIFY_URL_MAP event notification can occur multiple times on a single request, occasionally with an empty string for the pszURL member. One known cause of this is a call to ServerSupportFunction with HSE_REQ_MAP_URL_TO_PATH.
• If integrated Windows authentication (also called NTLM authentication) is being negotiated, there are typically three requests and responses between the client and server. The SF_NOTIFY_END_OF_REQUEST notification will not occur on the second request when IIS responds to the client with a challenge. All other notifications occur as expected on this second request and response. For this reason, you should not rely on this notification as a signal to free any memory allocated elsewhere in your filter unless you know integrated Windows authentication is not being used.
• You can use the SF_REQ_DISABLE_NOTIFICATIONS ServerSupportFunction to disable all further notifications, for the duration of the current request, if your filter has completed all processing for the request.
• Priority ratings for filters (high, medium, low) are temporarily reversed for any filters that participate in the SF_NOTIFY_SEND_RAW_DATA event notifications, for the duration of the notification. This reversal allows higher priority filters, such as encryption filters, to process the data after other raw data filters have operated on the unprocessed data, and just before the data is sent to the client browser. The priority ratings are unchanged for SF_NOTIFY_READ_RAW_DATA events notifications.