HttpFilterProc

IIS calls the HttpFilterProc entry point for each event notification which the filter has registered. IIS uses this function to pass information to the ISAPI filter regarding the notification. The filter uses this information to respond to the event. 

DWORD WINAPI HttpFilterProc(
  PHTTP_FILTER_CONTEXT pfc,  
  DWORD notificationType,  
  LPVOID pvNotification  
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT structure that contains context information.
notificationType
Indicates the type of event being processed. Following are the valid types:
Value Meaning
SF_NOTIFY_AUTHENTICATION The server is authenticating the client. This event only occurs during authentication of a net session. For example, if a keep-alive request has been negotiated and the client makes multiple requests on the same socket, this notification will not occur once the initial authentication has been completed. This notification is only for Anonymous and Basic authentication requests. Windows NTŪ Challenge/Response requests are handled internally by the server.
SF_NOTIFY_END_OF_REQUEST Notify the application that the filter is called at the end of every request, thus allowing the filter to clean up resources on a per-request basis. The network connection will remain open when the notification is called.
SF_NOTIFY_SECURE_PORT Notify the application only for sessions over a secure port.
SF_NOTIFY_NONSECURE_PORT Notify the application only for sessions over a nonsecure port.
SF_NOTIFY_READ_RAW_DATA Allow the application to see the raw data. The data returned will contain both headers and data. This notification may be called more than one time by a single request. Notifications for multiple requests may be made on the same pfc if the client and server have agreed to a keep-alive request.
SF_NOTIFY_PREPROC_HEADERS The server has preprocessed the headers. This notification occurs once per request. The HTTP_FILTER_CONTEXT GetServerVariable may not retrieve client headers until this notification has occurred.
SF_NOTIFY_URL_MAP The server is mapping a logical URL to a physical path. The server translates the base URL, but it also translates PATH_INFO into PATH_TRANSLATED. In addition, the ISAPI application may translate the URL.

If a filter retrieves the PATH_TRANSLATED or PATH_INFO server variables within the SF_NOTIFY_URL_MAP notification, the filter will be called recursively with the SF_NOTIFY_URL_MAP notification to do the physical translation for the variable. Care should be taken to prevent endless recursion in this specific scenario.
SF_NOTIFY_SEND_RAW_DATA The server is sending raw data back to the client. This notification may be called more than one time by a single request. Notifications for multiple requests may be made on the same pfc if the client and server have agreed to a keep-alive request.
SF_NOTIFY_LOG The server is writing information to the server log. This notification occurs once per response.
SF_NOTIFY_END_OF_NET_SESSION The session with the client is ending. If a keep-alive request has been negotiated between the client and the server and multiple requests are sent over the same socket, this notification will only occur after the net session is closed.
SF_NOTIFY_ACCESS_DENIED allows an ISAPI Filter to be notified any time the server is about to return a 401 Access Denied error message. This lets the filter analyze the failure and return a custom message.
SF_NOTIFY_SEND_RESPONSE This is similar in function to SF_NOTIFY_PREPROC_HEADERS, however it concerns headers that are being sent to the client. A filter can inspect, add, or delete headers the client will receive for a particular request.

pvNotification
The notification-specific structure.
Notification Type pvNotification points to
SF_NOTIFY_READ_RAW_DATA HTTP_FILTER_RAW_DATA
SF_NOTIFY_SEND_RAW_DATA HTTP_FILTER_RAW_DATA
SF_NOTIFY_PREPROC_HEADERS HTTP_FILTER_PREPROC_HEADERS
SF_NOTIFY_AUTHENTICATION HTTP_FILTER_AUTHENT
SF_NOTIFY_URL_MAP HTTP_FILTER_URL_MAP
SF_NOTIFY_LOG HTTP_FILTER_LOG
SF_NOTIFY_ACCESS_DENIED HTTP_FILTER_ACCESS_DENIED
SF_NOTIFY_SEND_RESPONSE HTTP_FILTER_SEND_RESPONSE

Return Values

Returns one of the following values that indicate how the application handled the event.

Value Meaning
SF_STATUS_REQ_FINISHED The filter has handled the HTTP request. The server should disconnect the session.
SF_STATUS_REQ_FINISHED_KEEP_CONN This is the same as SF_STATUS_REQ_FINISHED, except that the server should keep the TCP session open if the option was negotiated.
SF_STATUS_REQ_NEXT_NOTIFICATION The next filter in the notification chain should be called.
SF_STATUS_REQ_HANDLED_NOTIFICATION This filter handled the notification. No other handlers should be called for this particular notification type.
SF_STATUS_REQ_ERROR An error occurred. The server should call GetLastError and indicate the error to the client. The HTTP request will generally be aborted when this status is returned. The client should call SetLastError with the nature of the failure.
SF_STATUS_REQ_READ_NEXT The filter is an opaque stream filter (encrypted/compressed HTTP requests) and the session parameters are being negotiated. This is valid only for raw-read notification. This notification indicates that the full request has not been received yet and the Web server should issue another read and notify the filter with the additional data read.

Remarks

This is where the core work of the ISAPI filters is done. The various structures pointed to by pvNotification contain data and function pointers specific to these operations. See the structure details for more information.

See Also

HTTP_FILTER_CONTEXT, HTTP_FILTER_RAW_DATA, HTTP_FILTER_PREPROC_HEADERS, HTTP_FILTER_AUTHENT, HTTP_FILTER_URL_MAP, HTTP_FILTER_LOG