FilterVolumeInstanceFindFirst-Funktion (fltuser.h)

Artikel
08/23/2023

Die FilterVolumeInstanceFindFirst-Funktion gibt Informationen zu einem Minifiltertreiber instance oder Legacyfiltertreiber zurück und wird verwendet, um mit der Überprüfung der Filtertreiber zu beginnen, die an ein Volume angefügt sind.

Syntax

HRESULT FilterVolumeInstanceFindFirst(
  [in]  LPCWSTR                    lpVolumeName,
  [in]  INSTANCE_INFORMATION_CLASS dwInformationClass,
  [out] LPVOID                     lpBuffer,
  [in]  DWORD                      dwBufferSize,
  [out] LPDWORD                    lpBytesReturned,
  [out] LPHANDLE                   lpVolumeInstanceFind
);

Parameter

[in] lpVolumeName

Zeiger auf eine mit NULL beendete Breitzeichenzeichenfolge, die den Namen des Volumes enthält, an das der Minifilter instance oder Legacyfilter angefügt ist.

Die Eingabezeichenfolge lpVolumeName kann wie folgt aussehen. Der nachfolgende umgekehrte Schrägstrich (\) ist optional.

Ein Laufwerkbuchstabe, z. B. D:\
Ein Pfad zu einem Volumeeinbindungspunkt, z. B. c:\mnt\edrive\
Ein eindeutiger Volumebezeichner (auch als Volume-GUID-Name bezeichnet), z. B. \?? \Volume{7603f260-142a-11d4-ac67-806d6172696f}\
Ein nicht permanenter Gerätename (auch als Zielname oder NT-Gerätename bezeichnet), z. B. \Device\HarddiskVolume1\

[in] dwInformationClass

Der Typ der zurückgegebenen Filtertreiberinformationsstruktur. Dieser Parameter muss einen der folgenden Werte enthalten.

Wert	Bedeutung
InstanceBasicInformation	Gibt eine INSTANCE_BASIC_INFORMATION-Struktur für einen Minifilter-instance zurück. Ältere Filtertreiber werden ignoriert.
InstanceFullInformation	Gibt eine INSTANCE_FULL_INFORMATION-Struktur für einen Minifilter-instance zurück. Ältere Filtertreiber werden ignoriert.
InstancePartialInformation	Gibt eine INSTANCE_PARTIAL_INFORMATION-Struktur für einen Minifilter-instance zurück. Ältere Filtertreiber werden ignoriert.
InstanceAggregateStandardInformation	Gibt eine INSTANCE_AGGREGATE_STANDARD_INFORMATION-Struktur für die instance zurück. Der LegacyFilter-Member 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 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 FilterVolumeInstanceFindFirst erfolgreich ist. Dieser Parameter ist erforderlich und darf nicht NULL sein.

[out] lpVolumeInstanceFind

Zeiger auf eine vom Aufrufer zugeordnete Variable, die ein Suchhandle für den Minifilter instance oder Legacyfilter empfängt (nur, wenn InstanceAggregateStandardInformation angegeben ist), wenn der Aufruf von FilterVolumeInstanceFindFirst erfolgreich ist. Andernfalls empfängt lpVolumeInstanceFind INVALID_HANDLE_VALUE. Dieses Suchhandle kann in nachfolgenden Aufrufen von FilterVolumeInstanceFindNext und FilterVolumeInstanceFindClose verwendet werden.

Rückgabewert

FilterVolumeInstanceFindFirst 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 InstanceAggregateStandardInformation für ein Betriebssystem vor Windows Vista angegeben ist, gibt FilterVolumeInstanceFindFirst diesen HRESULT-Wert zurück.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	Auf dem angegebenen Volume wurde kein Filtertreiber gefunden.

Hinweise

Die FilterVolumeInstanceFindFirst-Funktion öffnet ein Suchhandle und gibt Informationen zum ersten gefundenen Filtertreiber zurück, der an das Volume mit dem Namen lpVolumeName angefügt ist. Nachdem das Suchhandle eingerichtet wurde, rufen Sie FilterVolumeInstanceFindNext auf, um nach anderen Filtertreibern zu suchen, die an dasselbe Volume angefügt sind. Wenn das Suchhandle nicht mehr benötigt wird, schließen Sie es, indem Sie FilterVolumeInstanceFindClose aufrufen.

Ab Windows Vista kann FilterVolumeInstanceFindFirst sowohl Legacyfiltertreiberinformationen als auch Minifiltertreiberinformationen instance Informationen zurückgeben, wenn der Wert des dwInformationClass-ParametersInstanceAggregateStandardInformation ist. Bei früheren Betriebssystemen kann diese Funktion keine Legacyfilterinformationen zurückgeben, da die INSTANCE_AGGREGATE_STANDARD_INFORMATION-Struktur nicht verfügbar ist.