ISAPI フィルタ概要

ISAPI フィルタ

ISAPI フィルタ (Filter) は ISAPI エクステンション (Extension, 拡張) と並び、IIS の早期のバージョンから実装されている API のひとつです。ISAPI エクステンションが Script Handler エンジン的あるいは CGI 的に使用されるのに対して、 ISAPI フィルタは IIS の内部処理を横取りしてIISをカスタマイズすることを可能とするための API です。

例: http://hostname/vdir/foo.htm に対応する物理ファイルを C:\wwwroot\foo.htm から D:\myfolder\bar.htm に差し替える
HTTP 圧縮・ SSL 等の機能は ISAPI フィルタで実装されている

例: スタティックコンテンツの HTTP 圧縮

例として IIS 6 の HTTP 圧縮実装例をあげます。

compfilt.dll に実装されている
URL と物理ファイルのマッピングを変更(SF_NOTIFY_URL_MAP)

ISAPI フィルタ DLL の構成

ISAPI フィルタは DLL として実装されており、次の関数をエクスポートしなければなりません。

三つの関数をエクスポートする

GetFilterVersion: DLLのロード時に呼び出される
HttpFilterProc: 通知ごとにそれぞれ特有のデータを受け取る。戻り値に特定の値を返すことでフィルターの動作を細かく制御できる。
TerminateFilter: DLLのアンロード時に呼び出される

通知の種類

IIS の内部処理の様々な段階それぞれについて、ISAPI が通知を受けることができます。以下がそれぞれの通知です。自己記述的な通知名なのでおよそその内容の見当がつくのではないでしょうか。

SF_NOTIFY_READ_RAW_DATA
SF_NOTIFY_PREPROC_HEADERS
SF_NOTIFY_URL_MAP
SF_NOTIFY_AUTHENTICATION
SF_NOTIFY_AUTH_COMPLETE
SF_NOTIFY_SEND_RESPONSE
SF_NOTIFY_SEND_RAW_DATA
SF_NOTIFY_END_OF_REQUEST
SF_NOTIFY_END_OF_NET_SESSION

戻り値

ISAPI は戻り値によって、通知のチェーンを断ち切ることも処理を終わらせることも、もちろん継続することも可能です。

SF_STATUS_REQ_FINISHED
SF_STATUS_REQ_FINISHED_KEEP_CONN
SF_STATUS_REQ_NEXT_NOTIFICATION
SF_STATUS_REQ_HANDLED_NOTIFICATION
SF_STATUS_REQ_ERROR
SF_STATUS_REQ_READ_NEXT

戻り値は次の図のように使われます。

ISAPI Filter 開発のヒント

知っていると便利（というか知らないときつい）点を三つだけあげてみました。

フィルタで使うメモリの割り当て - AllocMem
pFilterContext の使い方
SF_STATUS_REQ_READ_NEXT

それぞれみていきましょう。

AllocMem

フィルタ内でメモリを割り当てるときは AllocMem を使う
AllocMem で割り当てたメモリは自動的に解放される

pFilterContext

フィルターコンテキストを通して使えるユーザーデータの格納場所
初期値は NULL を仮定してよい

２番目の点は意外と重要で、pFilterContext が NULL の場合が初期化されていない状態と考えて大丈夫です。過去に MS の Redmond の開発者からコードレビュー等も受けたことがありますので、ドキュメントされていないのですが大丈夫と考えてよいでしょう。

SF_STATUS_REQ_READ_NEXT

HttpFilterProc で SF_STATUS_REQ_READ_NEXT を返すと、Raw データの読み込みを連続したデータ領域として扱うことが可能になる
HTTP ヘッダーの改変時に必須

IIS 5 が HTTP のヘッダの折り返しをサポートしないので、その回避方法として HTTP ヘッダを改変したことがあるのですが、その時にこの通知を利用したことで大変楽に実装できました。