IFilter

COM

IID89bcb740-6119-101a-bcb7-00dd010655af継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

ドキュメントをスキャンしてテキストとプロパティ(属性とも呼ばれます)を取得します。

解説(Remarks)

Indexing Service 用の IFilter コンポーネントは Local Security コンテキストで実行されるため、バッファーを適切に管理し、スタックを正しく扱うように記述する必要があります。すべての文字列コピーには、バッファーオーバーランを防ぐための明示的なチェックを設けなければなりません。常にバッファーの割り当てサイズを確認し、データのサイズをバッファーのサイズと比較して検証してください。

以前は、IFilter が返すデータは字句的にのみインデックス付けされていました。Windows 11 バージョン 26100 以降では、IFilter が返すデータは意味的にもインデックス付けされます。たとえば、「pasta」を検索したユーザーが「lasagna」の結果も得られる場合があります。同じく Windows 11 バージョン 26100 以降では、IPixelFilter によって画像の意味的なインデックス付けが可能になります。

メソッド 5

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 INT Init(DWORD grfFlags, DWORD cAttributes, FULLPROPSPEC* aAttributes, DWORD* pFlags)

フィルター処理セッションを初期化します。

grfFlags	DWORD	in	テキストの標準化、プロパティの出力、埋め込みオブジェクトのスコープ、および IFilter のアクセスパターンを制御するための IFILTER_INIT 列挙型の値。
cAttributes	DWORD	in	属性配列のサイズ。0 以外の場合、cAttributes は grfFlags で指定された属性よりも優先されます。属性フラグが指定されず、かつ cAttributes が 0 の場合、既定では PSGUID_STORAGE ストレージプロパティセット(ファイルへの最終書き込みの日付と時刻、サイズなどを含む)と、ファイルの主要な内容にマップされる PID_STG_CONTENTS 'contents' プロパティが使用されます。プロパティおよびプロパティセットの詳細については、Property Sets を参照してください。
aAttributes	FULLPROPSPEC*	in	要求するプロパティを表す FULLPROPSPEC 構造体の配列へのポインター。cAttributes が 0 以外の場合、aAttributes に含まれるプロパティのみが返されます。
pFlags	DWORD*	out	呼び出し元が利用できる追加プロパティに関する情報。IFILTER_FLAGS 列挙型の値です。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	操作は正常に完了しました。
E_FAIL	フィルター対象のファイルが事前に読み込まれていません。
E_INVALIDARG	属性の個数と内容が一致しません。
FILTER_E_PASSWORD	パスワード保護または同様のセキュリティ対策のため、アクセスが拒否されました。
FILTER_E_ACCESS	一般的なアクセス失敗。

解説(Remarks)

Init メソッドはフィルターオブジェクトの状態を設定します。コンテンツフィルターはオブジェクトの先頭に位置付けられ、オブジェクトが解放されるまでその状態は固定されます。aAttributes 配列にプロパティセットとプロパティ識別子 (ID) の記述を設定することで、返してほしいプロパティの集合をフィルターオブジェクトに渡せます。詳細については、Filtering File Properties を参照してください。

呼び出し元に対する注意

他のすべての IFilter メソッドを呼び出す前に、Init メソッドを呼び出してください。

実装者に対する注意

同一のパラメーターで Init メソッドを複数回呼び出した場合、チャンク ID は一貫している必要があります。

IFilter インターフェイスの実装によっては、Init メソッドが呼び出されるまで(あるいはそれ以降まで)、ドキュメントへのアクセス失敗を検出できない場合や、検出に大きな計算コストがかかる場合があります。

vtbl 4 INT GetChunk(STAT_CHUNK* pStat)

フィルターを次のチャンクの先頭(GetChunk メソッドの初回呼び出しの場合は最初のチャンク)に位置付け、現在のチャンクの説明を返します。

pStat

STAT_CHUNK*

out

現在のチャンクの説明を格納する STAT_CHUNK 構造体へのポインター。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	操作は正常に完了しました。
FILTER_E_END_OF_CHUNKS	直前のチャンクが最後のチャンクです。
FILTER_E_EMBEDDING_UNAVAILABLE	次のチャンクは埋め込みオブジェクトですが、利用可能なコンテンツフィルターがありません。
FILTER_E_LINK_UNAVAILABLE	次のチャンクはリンクですが、利用可能なコンテンツフィルターがありません。
FILTER_E_PASSWORD	パスワードまたはその他のセキュリティ関連のアクセス失敗です。
FILTER_E_ACCESS	一般的なアクセス失敗。

解説(Remarks)

戻り時に pStat が指す STAT_CHUNK 構造体の breakType メンバーが CHUNK_NO_BREAK である場合、更新されるのは新しいチャンク識別子 (ID) の値を持つ idChunk メンバーのみです。STAT_CHUNK 構造体のその他のメンバーは変更されません。

内部の値型プロパティ(CHUNKSTATE 列挙値が CHUNK_VALUE のチャンク)は、CHUNK_NO_BREAK を使って連結することはできません。1 つの単語が 3 つ以上の連結されたチャンクにまたがることはできません。

チャンク ID の 0 は無効です。

GetChunk メソッドが初めて呼び出される前は、現在のチャンクは存在しません。FILTER_E_END_OF_CHUNKS 以外のエラーコードが返された場合でも、次に GetChunk メソッドを呼び出すと、利用できなかったチャンクの次のチャンクが取得されます。

呼び出し元に対する注意

GetChunk メソッドが完了すると、*pStat に記述されたチャンクが現在のチャンクになります。チャンク記述子は GetChunk メソッドを呼び出したルーチンが所有しますが、プロパティ仕様に設定できるプロパティ名ポインターは GetChunk メソッドが所有するため、解放してはいけません。

実装者に対する注意

リンクされたオブジェクトまたは埋め込みオブジェクトのコンテンツフィルターに対する GetChunk メソッドの呼び出しが FILTER_E_END_OF_CHUNKS を返した場合、実装はリンク元または埋め込み元のオブジェクトの次のチャンクを返す必要があります。たとえば、ドキュメントに 2 つの埋め込みオブジェクトがあり、最初のオブジェクトが FILTER_E_END_OF_CHUNKS を返した場合、外側のコンテンツフィルターは埋め込みオブジェクト用のコンテンツフィルターの GetChunk メソッドを呼び出さなければなりません。

埋め込みオブジェクトまたはリンクされたオブジェクトに対する GetChunk メソッドの呼び出し結果を返す前に、チャンク ID が一意であることを確認してください。一意でない場合、実装者はチャンクに番号を振り直し、新しいチャンク ID のマッピングを保持する必要があります。

vtbl 5 INT GetText(DWORD* pcwcBuffer, LPWSTR awcBuffer)

現在のチャンクからテキスト(テキスト型プロパティ)を取得します。チャンクの CHUNKSTATE 列挙値は CHUNK_TEXT でなければなりません。

pcwcBuffer	DWORD*	inout	入力時は、awcBuffer 配列のサイズ(ワイド/Unicode 文字数)。出力時は、awcBuffer に書き込まれた Unicode 文字数。
awcBuffer	LPWSTR	out	現在のチャンクから取得したテキスト。バッファーを文字で終端しないでください。null 終端文字列を使用します。null 終端文字列は、コピー先バッファーのサイズを超えてはいけません。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	操作は正常に完了しました。
FILTER_E_NO_TEXT	現在のチャンクの STAT_CHUNK 構造体の flags メンバーの値が CHUNK_TEXT ではありません。
FILTER_E_NO_MORE_TEXT	現在のチャンク内のすべてのテキストが返されました。IFilter::GetChunk メソッドが正常に呼び出されるまで、GetText メソッドを追加で呼び出してもこのエラーが返されます。
FILTER_S_LAST_TEXT	最適化として、テキストを返す最後の呼び出しが FILTER_S_LAST_TEXT を返すことがあります。これは、次回の GetText メソッドの呼び出しが FILTER_E_NO_MORE_TEXT を返すことを示します。この最適化により、不要な GetText の呼び出しを省いて時間を節約できます。

解説(Remarks)

現在のチャンクが awcBuffer 配列に収まらないほど大きい場合、そのチャンク内のすべてのテキストを取得するために GetText メソッドを複数回呼び出す必要があります。GetText メソッドの各呼び出しでは、前回の GetText メソッドの呼び出しで取得したテキストの直後に続くテキストが取得されます。ある呼び出しの最後の文字が単語の途中になり、次の呼び出しの最初の文字がその単語の続きになることがあります。検索エンジンはこの状況に対処する必要があります。

vtbl 6 INT GetValue(PROPVARIANT** ppPropValue)

チャンクから値(内部の値型プロパティ)を取得します。チャンクの CHUNKSTATE 列挙値は CHUNK_VALUE でなければなりません。

ppPropValue

PROPVARIANT**

out

値型プロパティを格納する PROPVARIANT 構造体へのポインターを受け取る出力変数へのポインター。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	操作は正常に完了しました。
FILTER_E_NO_MORE_VALUES	このチャンクに対して GetValue メソッドが既に呼び出されています。IFilter::GetChunk メソッドが正常に呼び出されて次のチャンクへ進むまで、この値が返されます。
FILTER_E_NO_VALUES	現在のチャンクの CHUNKSTATE 列挙値が CHUNK_VALUE ではありません。

解説(Remarks)

GetValue メソッドは、1 つのチャンクにつき 1 回だけ呼び出してください。

複数のチャンクから同じ値を生成した場合の動作は未定義であることに注意してください。有効なのは最後に設定された値のみです。

呼び出し元に対する注意

PROPVARIANT 構造体は CoTaskMemAlloc で割り当ててください。一部の PROPVARIANT 構造体はポインターを含んでおり、PropVariantClear 関数を呼び出すことで解放できます。PropVariantClear を呼び出す責任は GetValue メソッドの呼び出し元にあります。

vtbl 7 INT BindRegion(FILTERREGION origPos, GUID* riid, void** ppunk)

オブジェクトの指定された部分を表すインターフェイスを取得します。現在は将来の使用のために予約されています。

origPos	FILTERREGION	in	テキストの位置を格納する FILTERREGION 構造体。
riid	GUID*	in	要求するインターフェイス識別子への参照。
ppunk	void**	out	riid で要求したインターフェイスポインターを受け取る変数へのポインター。正常に復帰すると、*ppunk には要求されたインターフェイスポインターが格納されます。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	操作は正常に完了しました。
E_NOTIMPL	このメソッドは現在実装されていません。
FILTER_W_REGION_CLIPPED	フィルターは領域全体をバインドできませんでした。

解説(Remarks)

BindRegion メソッドが指定された領域にインターフェイスをバインドできない場合は、FILTER_W_REGION_CLIPPED を返します。この状況は、対象となる次のチャンクがリンクされたオブジェクトまたは埋め込みオブジェクト内にある場合に発生することがあります。

すべてのフィルターが BindRegion メソッドを合理的な形でサポートできるわけではありません。このメソッドの恩恵を最も受けるのは、表示アプリケーションによって実装されるフィルターです。このメソッドは、検索エンジンを経由して IFilter インターフェイスの実装へ Cookie を受け渡す手段として意図されています。

実装者に対する注意

このメソッドは現在、将来の使用のために予約されています。常に E_NOTIMPL を返してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IFilter "{89BCB740-6119-101A-BCB7-00DD010655AF}"
#usecom global IFilter IID_IFilter "{}"
#comfunc global IFilter_Init        3 int,int,var,var
#comfunc global IFilter_GetChunk    4 var
#comfunc global IFilter_GetText     5 var,var
#comfunc global IFilter_GetValue    6 var
#comfunc global IFilter_BindRegion  7 int,var,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IFilter "{89BCB740-6119-101A-BCB7-00DD010655AF}"
#usecom global IFilter IID_IFilter "{}"
#comfunc global IFilter_Init        3 int,int,sptr,sptr
#comfunc global IFilter_GetChunk    4 sptr
#comfunc global IFilter_GetText     5 sptr,sptr
#comfunc global IFilter_GetValue    6 sptr
#comfunc global IFilter_BindRegion  7 int,sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。