Windows Search でのフィルターハンドラーの実装

[アーティクル]
06/13/2023

フィルターハンドラーの必要な DLL 構造 ( IFilter インターフェイスの実装) を理解しておくことが重要です。

このトピックは次のように整理されています。

DLL エントリポイントの実装とエクスポート
IFilter クラスとクラスファクトリの実装
COM インターフェイスの継承
COM インターフェイスメソッドの実装
- 実装されていない COM メソッド
その他のリソース
関連トピック

DLL エントリポイントの実装とエクスポート

各 IFilter DLL (このセクションのIfilter.dllで示されます) は、次のエントリポイントを実装してエクスポートする必要があります。これらのエントリポイントは、通常、IFilter インターフェイスのモジュール定義 (.def) ファイルを使用するか、__declspec(dllexport) キーワード (keyword)を使用してエクスポートされます。 DLL ファイルは任意のフォルダーに登録できますが、通常は %SystemRoot%\system32 フォルダーに存在します。

DLL エントリポイントの一覧と説明を次の表に示します。

DLL 名	DLL の説明
DllRegisterServer	DllRegisterServer エントリポイントは、DLL をフィルターとしてレジストリに登録します。 DLL を登録する場合は、 IFilter インターフェイス DLL ファイル名を引数として使用してregsvr32.exe プログラムを実行します。 `regsvr32.exe %SystemRoot%\system32\Ifilter.dll`
DllUnregisterServer 関数	DllUnregisterServer 関数エントリポイントは、レジストリ内の永続的なハンドラーとして DLL を削除します。フラグを使用してregsvr32.exe プログラムを実行して、DLL の登録を `/u` 解除します。 `regsvr32.exe /u %SystemRoot%\system32\Ifilter.dll`
DllGetClassObject 関数	コンテンツインデックス作成クライアントは、コンポーネントオブジェクトモデル (COM) を介して DllGetClassObject 関数エントリポイントを呼び出して、 IFilter インターフェイスのクラスファクトリオブジェクトを作成し、そのオブジェクトのクラスファクトリインターフェイスへのポインターを取得します。
DllCanUnloadNow 関数	コンテンツインデックス作成クライアントは、COM を介して DllCanUnloadNow 関数エントリポイントを呼び出して、 IFilter DLL をアンロードできるかどうかを判断します。 IFilter インターフェイスは、FilterIdleTimeOut レジストリ値で指定されているように、一定時間使用されていないとアンロードされます。

IFilter クラスとクラスファクトリの実装

CFilter や CFilterCF などの少なくとも 2 つのクラスは、通常、各 IFilter DLL によって実装されます。 CFilter クラスは、コンテンツフィルター機能を実装する IFilter インターフェイスオブジェクトを生成します。そのメンバー関数は、 IFilter インターフェイスのインターフェイスメソッドを実装します。各 IFilter クラスには、 IFilter インターフェイス実装者が生成する一意のクラス識別子 (CLSID) が必要です。

CFilterCF クラスは、 IFilter インターフェイスのクラスファクトリオブジェクトを生成します。クラスファクトリは、 IClassFactory インターフェイスインターフェイスを介して、 DLL の DllGetClassObject 関数エントリポイントによって呼び出されます。 CFilterCF クラスは CFilter オブジェクトを作成し、 IUnknown へのポインターを返します。より複雑なケースでは、 IFilter は単一の CFilter クラスの代わりにクラス階層を実装できます。

COM インターフェイスの継承

Windows Search 3.0 以降では、次の理由で IPersistStream を使用する必要があります。

パフォーマンスと将来の互換性を確保するため。
セキュリティの強化に役立ちます。 IPersistStream で実装された IFilter は、IFilter インターフェイスが実行されるコンテキストに、ディスク上またはネットワーク経由でファイルを開く権限が必要ないため、より安全です。
Windows Search では IPersistStream のみが使用されますが、 IFilter インターフェイスクラスは、下位互換性のために IPersistFile インターフェイスおよび IPersistStorage インターフェイスの実装を継承することもできます。

これらのインターフェイスは、mssdk\include ディレクトリから含まれるファイルで宣言され、定義済みのインターフェイス識別子 (IID) を持ちます。コンテンツインデックス作成クライアントは、IUnknown を介して IFilter インターフェイスに対してクエリを実行して、コンテンツをフィルター処理するときに使用するこれらのインターフェイスを決定します。

COM インターフェイスメソッドの実装

IFilter インターフェイスは、IFilter インターフェイスクラスと IFilter インターフェイスクラスファクトリの両方にIUnknown メソッドを実装します。次の表は、vtable の順序で、 IFilter インターフェイス固有のインターフェイスと IFilter インターフェイスが実装する必要があるメソッドの一覧です。 IFilter インターフェイスは、少なくとも IPersistStream を実装する必要がありますが、追加の IPersist 派生インターフェイスを実装できます。

COM インターフェイス	メソッド
IClassFactory インターフェイス	CreateInstance、LockServer
IClassFactory2 インターフェイス	GetLicInfo、RequestLicKey、CreateInstanceLic
Ifilter	IFilter::Init、 IFilter::GetChunk、 IFilter::GetText、 IFilter::GetValue、 IFilter::BindRegion
IPersist インターフェイス	GetClassID
IPersistFile インターフェイス	IsDirty、Load、Save、SaveCompleted、GetCurFile
IPersistStorage インターフェイス	IsDirty、Load、Save、GetSizeMax
IPersistStream	IsDirty、Load、Save、GetSizeMax

各メソッドの参照ページでは、そのメソッドのパラメーターと機能動作を指定します。各参照ページには、そのメソッドに実装する結果コードも示されます。 IFilter メソッドの参照ページでは、実装FACILITY_ITF結果コード内のインターフェイス固有のコードが提供されます。また、コンテンツインデックス作成クライアントは、FACILITY_NULLやFACILITY_WIN32などの一般的な結果コードを処理することもできます。詳細については、「 COM エラーコードの構造」を参照してください。

実装されていない COM メソッド

IFilter インターフェイスは、少なくとも IPersistStream を実装する必要がありますが、追加の IPersist 派生インターフェイスを実装する必要はありません。

Windows Search では、次の表に示す COM メソッドを実装する必要はありません。

不要なメソッド	説明
IPersistStream::IsDirty	フィルターはE_NOTIMPLを返す必要があります。
IPersistStream::Save	フィルターはE_NOTIMPLを返す必要があります。
IPersistStream::GetSizeMax	フィルターはE_NOTIMPLを返す必要があります。
IFilter::BindRegion	フィルターはE_NOTIMPLを返す必要があります。

その他のリソース

GitHub で入手できる IFilterSample コードサンプルは、IFilter インターフェイスを実装するための IFilter 基本クラスを作成する方法を示しています。
インデックス作成プロセスの概要については、「インデックス作成プロセス」を参照してください。
ファイルの種類の概要については、「ファイルの種類」を参照してください。
ファイルの種類のファイル関連付け属性を照会するには、「 PerceivedTypes、SystemFileAssociations、およびアプリケーション登録」を参照してください。