FilterFindFirst 函式 (fltuser.h)

發行項
02/26/2024

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 與篩選管理員匯總。 For more information about the filter manager rollup package for Windows XP with SP2, see article 914882, " The filter manager rollup package for Windows XP SP2," in the Microsoft Knowledge Base.
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 錯誤值，例如下列其中一項：

傳回碼	Description
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 會傳回篩選驅動程式的相關信息，以便從基底文件系統減少距離。會先傳回與基底文件系統最遠的篩選條件相關信息。第二個最遠篩選的相關信息會傳回第二個。最後會傳回最接近基底文件系統的篩選條件相關信息。

如果輸入 dwBufferSize 太小， lpFilterFind 會收到INVALID_HANDLE_VALUE，而 lpBytesReturned 會收到儲存要求資訊所需的位元組數目。