FilterFindFirst 関数 (fltuser.h)

[アーティクル]
08/23/2023

FilterFindFirst 関数は、フィルタードライバー (ミニフィルタードライバーインスタンスまたはレガシフィルタードライバー) に関する情報を返し、登録されているフィルターのグローバルリスト内のフィルターのスキャンを開始するために使用されます。

構文

HRESULT FilterFindFirst(
  [in]  FILTER_INFORMATION_CLASS dwInformationClass,
  [out] LPVOID                   lpBuffer,
  [in]  DWORD                    dwBufferSize,
  [out] LPDWORD                  lpBytesReturned,
  [out] LPHANDLE                 lpFilterFind
);

パラメーター

[in] dwInformationClass

要求されたフィルタードライバー情報の種類。このパラメーターには次のいずれかの値を指定する必要があります。

値	意味
FilterFullInformation	lpBuffer パラメーターが指すバッファーは、各ミニフィルターインスタンスのFILTER_FULL_INFORMATION構造体を受け取ります。レガシフィルターは無視されます。
FilterAggregateBasicInformation	lpBuffer パラメーターが指すバッファーは、ミニフィルターインスタンスまたはレガシフィルターごとにFILTER_AGGREGATE_BASIC_INFORMATION構造体を受け取ります。この dwInformationClass 値は、Windows Server 2003 SP1 以降、Windows XP と SP2 フィルターマネージャーロールアップで使用できます。 SP2 を使用した Windows XP のフィルターマネージャーロールアップパッケージの詳細については、マイクロソフトサポート技術情報の「windows XP SP2 のフィルターマネージャーロールアップパッケージ」914882記事を参照してください。
FilterAggregateStandardInformation	lpBuffer パラメーターが指すバッファーは、ミニフィルターインスタンスまたはレガシフィルターごとにFILTER_AGGREGATE_STANDARD_INFORMATION構造体を受け取ります。この dwInformationClass 値は、Windows Vista 以降で使用できます。

[out] lpBuffer

要求された情報を受信する呼び出し元によって割り当てられたバッファーへのポインター。バッファーで返される情報の型は、 dwInformationClass パラメーターによって定義されます。

[in] dwBufferSize

lpBuffer パラメーターが指すバッファーのサイズ (バイト単位)。呼び出し元は、指定された dwInformationClass に従ってこのパラメーターを設定する必要があります。

[out] lpBytesReturned

FilterFindFirst の呼び出しが成功した場合に lpBuffer が指すバッファーで返されるバイト数を受け取る呼び出し元によって割り当てられた変数へのポインター。このパラメーターは必須であり、 NULL にすることはできません。

[out] lpFilterFind

FilterFindFirst の呼び出しが成功した場合にフィルタードライバーの検索ハンドルを受け取る呼び出し元によって割り当てられた変数へのポインター。それ以外の場合は、INVALID_HANDLE_VALUEを受け取ります。この検索ハンドルは、FilterFindNext と FilterFindClose の後続の呼び出しで使用できます。

戻り値

FilterFindFirst は、成功した場合S_OKを返します。それ以外の場合は、次のいずれかの HRESULT エラー値を返します。

リターンコード	説明
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	lpBuffer が指すバッファーは、要求された情報を格納するのに十分な大きさではありません。この値が返されると、 lpBytesReturned には、指定された dwInformationClass 構造体に必要なバッファーのサイズ (バイト単位) が含まれます。
HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER)	dwInformationClass パラメーターに無効な値が指定されました。たとえば、Windows Vista より前のオペレーティングシステムに FilterAggregateStandardInformation が指定されている場合、 FilterFindFirst はこの HRESULT 値を返します。
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	登録されたフィルターのグローバル一覧にフィルタードライバーが見つかりませんでした。

注釈

FilterFindFirst 関数は、検索ハンドルを開き、登録されたフィルターのグローバルリストにある最初のフィルタードライバーに関する情報を返します。検索ハンドルが確立されたら、 FilterFindNext 関数を呼び出して、グローバルリスト内の他のフィルターを検索します。検索ハンドルが不要になったら、 FilterFindClose を呼び出して閉じます。

Microsoft Windows Server 2003 と SP1 および Windows XP Service Pack 1 (SP1) フィルターマネージャーロールアップ以降、 FilterFindFirst と FilterFindNext では、従来のフィルタードライバー情報とミニフィルタードライバーインスタンス情報を提供できます。以前のバージョンの Windows では、 FilterFindFirst と FilterFindNext はミニフィルターに関する情報のみを提供できます (上記の dwInformationClass パラメーターの説明を参照してください)。

FilterFindFirst と FilterFindNext は、基本ファイルシステムからの距離を減らす順序でフィルタードライバーに関する情報を返します。基本ファイルシステムから最も遠いフィルターに関する情報が最初に返されます。 2 番目に遠いフィルターに関する情報は、2 番目に返されます。基本ファイルシステムに最も近いフィルターに関する情報は最後に返されます。

入力 dwBufferSize が小さすぎる場合、 lpFilterFind はINVALID_HANDLE_VALUEを受け取り、 lpBytesReturned は要求された情報を格納するために必要なバイト数を受け取ります。