HttpFilterProc Function

  • Article

IIS calls the HttpFilterProc entry-point function whenever a notification event for which the filter has registered occurs. IIS uses this function to pass information and control to your ISAPI filter.

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

Parameters

  • pfc
    Points to the HTTP_FILTER_CONTEXT Structure that is associated with the current, active HTTP transaction.

  • notificationType
    Points to a bitmask that indicates the type of notification event being processed. Following are the valid event types, and the circumstances under which they might occur:

    Event notification constant

    Meaning

    SF_NOTIFY_READ_RAW_DATA

    Occurs when data is being read from the client. May occur more than once per request.

    SF_NOTIFY_PREPROC_HEADERS

    Occurs immediately after IIS has pre-processed headers, but before IIS has begun to process header content.

    SF_NOTIFY_URL_MAP

    Occurs after IIS has translated a URL to a physical path on the server.

    SF_NOTIFY_AUTHENTICATION

    Occurs just before IIS authenticates the client.

    SF_NOTIFY_ACCESS_DENIED

    Occurs just after IIS has determined that access is denied for the request resource, but before IIS has sent a response to the client.

    SF_NOTIFY_SEND_RESPONSE

    Occurs after the request has been processed by IIS, but before any headers are sent back to the client.

    SF_NOTIFY_SEND_RAW_DATA

    Occurs as IIS sends raw data back to the client. May occur more than once per request.

    SF_NOTIFY_END_OF_REQUEST

    Occurs at the end of the request.

    SF_NOTIFY_LOG

    Occurs at the end of a request, just before IIS writes the transaction to the IIS log.

    SF_NOTIFY_END_OF_NET_SESSION

    Occurs when the network session with the client is ending.

    Port security constant

    Meaning

    SF_NOTIFY_SECURE_PORT

    Notify the application only for connections over a secure port.

    SF_NOTIFY_NONSECURE_PORT

    Notify the application only for connections over a nonsecure port.

  • pvNotification
    The notification-specific structure that contains more information about the current context of the request. The pvNotifcation point is in the right column of the table below.

    Notification type

    Structure

    SF_NOTIFY_READ_RAW_DATA

    HTTP_FILTER_RAW_DATA Structure

    SF_NOTIFY_SEND_RAW_DATA

    HTTP_FILTER_RAW_DATA Structure

    SF_NOTIFY_PREPROC_HEADERS

    HTTP_FILTER_PREPROC_HEADERS Structure

    SF_NOTIFY_AUTHENTICATION

    HTTP_FILTER_AUTHENT Structure

    SF_NOTIFY_URL_MAP

    HTTP_FILTER_URL_MAP Structure

    SF_NOTIFY_LOG

    HTTP_FILTER_LOG Structure

    SF_NOTIFY_ACCESS_DENIED

    HTTP_FILTER_ACCESS_DENIED Structure

    SF_NOTIFY_SEND_RESPONSE

    HTTP_FILTER_SEND_RESPONSE Structure

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 filter is not supported.

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

Tells IIS that an error occurred during the processing of the request. The filter should call SetLastError with the nature of the failure, otherwise the client might get an unexpected response. IIS looks at GetLastError and the notification where the error occurred to decide what error to send to the client. For example, if the filter calls SetLastError with a "File not found" error, IIS will return a 404 to the client.

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 yet been received; the Web server should issue another read and notify the filter with the additional data read.

Remarks

This function usually serves as the dispatch for an ISAPI filter. Separate functions are often created to serve as handlers for the separate notifications, especially if the handling code is complicated.

Requirements

Client: Requires Windows XP Professional, Windows 2000 Professional, or Windows NT Workstation 4.0

Server: Requires Windows Server 2003, Windows 2000 Server, or Windows NT Server 4.0

Product: IIS

Header: Declared in httpfilt.h

Library: aspnet_filter.dll