FilterInstanceFindFirst-Funktion (fltuser.h)

Artikel
08/23/2023

Die FilterInstanceFindFirst-Funktion gibt Informationen zu einem Minifiltertreiber instance zurück und wird als Ausgangspunkt für die Überprüfung der Instanzen eines Minifilters verwendet.

Syntax

HRESULT FilterInstanceFindFirst(
  [in]  LPCWSTR                    lpFilterName,
  [in]  INSTANCE_INFORMATION_CLASS dwInformationClass,
  [out] LPVOID                     lpBuffer,
  [in]  DWORD                      dwBufferSize,
  [out] LPDWORD                    lpBytesReturned,
  [out] LPHANDLE                   lpFilterInstanceFind
);

Parameter

[in] lpFilterName

Zeiger auf eine mit NULL beendete breitzeichenige Zeichenfolge, die den Namen des Minifiltertreibers enthält, der die instance besitzt.

[in] dwInformationClass

Der Typ der zurückgegebenen instance Informationsstruktur. Dieser Parameter muss einen der folgenden Werte aufweisen.

Wert	Bedeutung
InstanceBasicInformation	Gibt eine INSTANCE_BASIC_INFORMATION-Struktur für die instance zurück.
InstanceFullInformation	Gibt eine INSTANCE_FULL_INFORMATION-Struktur für die instance zurück.
InstancePartialInformation	Gibt eine INSTANCE_PARTIAL_INFORMATION-Struktur für die instance zurück.
InstanceAggregateStandardInformation	Gibt eine INSTANCE_AGGREGATE_STANDARD_INFORMATION-Struktur für die instance zurück. Der LegacyFilter-Teil der Struktur wird nicht verwendet. Diese Struktur 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 Bytes. Der Aufrufer sollte diesen Parameter entsprechend der angegebenen dwInformationClass festlegen.

[out] lpBytesReturned

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

[out] lpFilterInstanceFind

Zeiger auf eine vom Aufrufer zugewiesene Variable, die ein Suchhandle für den Minifilter empfängt, wenn der Aufruf von FilterInstanceFindFirst erfolgreich ist; andernfalls empfängt sie INVALID_HANDLE_VALUE. Dieses Suchhandle kann in nachfolgenden Aufrufen von FilterInstanceFindNext und FilterInstanceFindClose verwendet werden.

Rückgabewert

FilterInstanceFindFirst 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, 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 InstanceAggregateStandardInformation für Betriebssysteme vor Windows Vista angegeben ist, gibt die Funktion diesen HRESULT-Wert zurück.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	Der vom lpFilterName-Parameter angegebene Minifilter verfügt nicht über eine instance im Dateisystemstapel.

Hinweise

Die FilterInstanceFindFirst-Funktion öffnet ein Suchhandle und gibt Informationen zu einem instance für den Minifilter mit dem Namen lpFilterName zurück. Nachdem das Suchhandle eingerichtet wurde, rufen Sie FilterInstanceFindNext auf, um nach anderen Instanzen desselben Minifilters zu suchen. Wenn das Suchhandle nicht mehr benötigt wird, schließen Sie es, indem Sie FilterInstanceFindClose aufrufen.