FilterFindFirst-Funktion (fltuser.h)

Artikel
08/23/2023

Die FilterFindFirst-Funktion gibt Informationen zu einem Filtertreiber (Minifiltertreiber instance oder Legacyfiltertreiber) zurück und wird verwendet, um mit der Überprüfung der Filter in der globalen Liste der registrierten Filter zu beginnen.

Syntax

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

Parameter

[in] dwInformationClass

Typ der angeforderten Filtertreiberinformationen. Dieser Parameter muss einen der folgenden Werte aufweisen.

Wert	Bedeutung
FilterFullInformation	Der Puffer, auf den der lpBuffer-Parameter verweist, empfängt eine FILTER_FULL_INFORMATION-Struktur für jeden Minifilter instance. Legacyfilter werden ignoriert.
FilterAggregateBasicInformation	Der Puffer, auf den der lpBuffer-Parameter verweist, empfängt eine FILTER_AGGREGATE_BASIC_INFORMATION-Struktur für jeden Minifilter instance oder Legacyfilter. Dieser dwInformationClass-Wert ist ab Windows Server 2003 mit SP1 und Windows XP mit SP2 mit Filter-Manager-Rollup verfügbar. Weitere Informationen zum Filter-Manager-Rolluppaket für Windows XP mit SP2 finden Sie in der Microsoft Knowledge Base im Artikel 914882 " Das Filter-Manager-Rolluppaket für Windows XP SP2".
FilterAggregateStandardInformation	Der Puffer, auf den der lpBuffer-Parameter verweist, empfängt eine FILTER_AGGREGATE_STANDARD_INFORMATION-Struktur für jeden Minifilter instance oder Legacyfilter. Dieser dwInformationClass-Wert ist ab Windows Vista verfügbar.

[out] lpBuffer

Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der die angeforderten Informationen empfängt. Der Typ der im Puffer zurückgegebenen Informationen wird durch den dwInformationClass-Parameter definiert.

[in] dwBufferSize

Größe des Puffers, auf den der lpBuffer-Parameter verweist, in Byte. Der Aufrufer sollte diesen Parameter entsprechend der angegebenen dwInformationClass festlegen.

[out] lpBytesReturned

Zeiger auf eine vom Aufrufer zugeordnete Variable, die die Anzahl von Bytes empfängt, die im Puffer zurückgegeben werden, auf den lpBuffer zeigt, wenn der Aufruf von FilterFindFirst erfolgreich ist. Dieser Parameter ist erforderlich und darf nicht NULL sein.

[out] lpFilterFind

Zeiger auf eine vom Aufrufer zugeordnete Variable, die ein Suchhandle für den Filtertreiber empfängt, wenn der Aufruf von FilterFindFirst erfolgreich ist; Andernfalls empfängt sie INVALID_HANDLE_VALUE. Dieses Suchhandle kann in nachfolgenden Aufrufen von FilterFindNext und FilterFindClose verwendet werden.

Rückgabewert

FilterFindFirst gibt bei erfolgreicher Ausführung S_OK zurück. Andernfalls wird ein HRESULT-Fehlerwert zurückgegeben, z. B. einer der folgenden:

Rückgabecode	Beschreibung
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	Der Puffer, auf den lpBuffer verweist, ist nicht groß genug, um die angeforderten Informationen zu enthalten. Wenn dieser Wert zurückgegeben wird, enthält lpBytesReturned die Größe des Puffers in Bytes, der für die angegebene dwInformationClass-Struktur erforderlich ist.
HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER)	Für den dwInformationClass-Parameter wurde ein ungültiger Wert angegeben. Wenn beispielsweise FilterAggregateStandardInformation für ein Betriebssystem vor Windows Vista angegeben ist, gibt FilterFindFirst diesen HRESULT-Wert zurück.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	In der globalen Liste der registrierten Filter wurde kein Filtertreiber gefunden.

Hinweise

Die FilterFindFirst-Funktion öffnet ein Suchhandle und gibt Informationen zum ersten Filtertreiber zurück, der in der globalen Liste der registrierten Filter gefunden wird. Nachdem das Suchhandle eingerichtet wurde, rufen Sie die FilterFindNext-Funktion auf, um nach anderen Filtern in der globalen Liste zu suchen. Wenn das Suchhandle nicht mehr erforderlich ist, schließen Sie es, indem Sie FilterFindClose aufrufen.

Ab Microsoft Windows Server 2003 mit SP1 und Windows XP mit Service Pack 1 (SP1) mit Filter-Manager-Rollup können FilterFindFirst und FilterFindNext Informationen zu Legacyfiltertreibern und Minifiltertreiberinformationen instance bereitstellen. In früheren Versionen von Windows können FilterFindFirst und FilterFindNext nur Informationen zu Minifiltern bereitstellen (siehe Beschreibung des dwInformationClass-Parameters oben).

FilterFindFirst und FilterFindNext geben Informationen zu Filtertreibern in der Reihenfolge des abnehmenden Abstands vom Basisdateisystem zurück. Zuerst werden Informationen zum Filter zurückgegeben, der am weitesten vom Basisdateisystem entfernt ist. Informationen zum zweitfernsten Filter werden sekundengenau zurückgegeben. Informationen zum Filter, der dem Basisdateisystem am nächsten ist, werden zuletzt zurückgegeben.

Wenn die Eingabe dwBufferSize zu klein ist, empfängt lpFilterFind INVALID_HANDLE_VALUE und lpBytesReturned die Anzahl der Bytes, die zum Speichern der angeforderten Informationen erforderlich sind.