FltGetVolumeInstanceFromName-Funktion (fltkernel.h)

Artikel
02/06/2025

Die FltGetVolumeInstanceFromName Routine gibt einen undurchsichtigen Instanzzeiger für die angegebene Minifiltertreiberinstanz auf dem angegebenen Volume zurück.

Syntax

NTSTATUS FLTAPI FltGetVolumeInstanceFromName(
  [in, optional] PFLT_FILTER      Filter,
  [in]           PFLT_VOLUME      Volume,
  [in, optional] PCUNICODE_STRING InstanceName,
  [out]          PFLT_INSTANCE    *RetInstance
);

Parameter

[in, optional] Filter

Undurchsichtiger Filterzeiger für den Minifiltertreiber, der die Instanz besitzt. Dieser Parameter ist optional und kann NULL-werden.

[in] Volume

Undurchsichtiger Zeiger für das Volume, an das die Instanz angefügt ist. Muss ein gültiger Volumehandle sein. Dieser Parameter ist erforderlich und kann nicht NULL-werden. (Wenn dieser Parameter auf einen ungültigen Wert festgelegt wird, wird das System bei einem überprüften Build bestätigt.)

[in, optional] InstanceName

Zeigen Sie auf eine vom Aufrufer zugewiesene UNICODE_STRING Struktur, die den Instanznamen für die Instanz auf dem Volume enthält. (Dies ist der InstanceName Wert, der beim Erstellen der Instanz an FltAttachVolume oder FltAttachVolumeAtAltitude übergeben wurde.) Dieser Parameter ist optional und kann NULL-werden. Wenn es NULL-ist, gibt FltGetVolumeInstanceFromName die höchste übereinstimmende Instanz zurück, die gefunden wird.

[out] RetInstance

Zeiger auf eine vom Aufrufer zugewiesene Variable, die einen undurchsichtigen Instanzzeiger für die Instanz empfängt, die den Werten für Filter-, Volume-und InstanceName-entspricht. Dieser Parameter ist erforderlich und kann nicht NULL-werden.

Rückgabewert

FltGetVolumeInstanceFromName gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert zurück, z. B. einen der folgenden:

Rückgabecode	Beschreibung
STATUS_FLT_DELETING_OBJECT	Die Instanz wird heruntergerissen. Dies ist ein Fehlercode.
STATUS_FLT_INSTANCE_NOT_FOUND	Es wurde keine übereinstimmende Instanz gefunden. Dies ist ein Fehlercode.

Bemerkungen

FltGetVolumeInstanceFromName durchsucht die Liste der Minifiltertreiberinstanzen, die mit dem volume verbunden sind, das im Parameter Volume angegeben ist, um die Höhe zu verringern, beginnend mit der obersten Instanz. Wenn mehrere Instanzen den angegebenen Werten für den Filter, Volume-und InstanceName Parameter entsprechen, gibt FltGetVolumeInstanceFromName die höchste gefundene Instanz zurück.

Der Begriff "Höhe" bezieht sich auf die Position, die eine Instanz im Minifilter-Treiberinstanzstapel für ein Volume belegt (oder belegen sollte). Je höher die Höhe ist, desto weiter liegt die Instanz vom Basisdateisystem im Stapel. Auf einem bestimmten Volume kann nur eine Instanz in einer bestimmten Höhe angefügt werden.

Die Höhe wird durch eine Höhenzeichenfolgeangegeben. Dabei handelt es sich um eine gezählte Unicode-Zeichenfolge, die aus einer oder mehreren Dezimalziffern von 0 bis 9 besteht, und sie kann einen einzelnen Dezimalkommapunkt enthalten. Beispielsweise sind "100.123456" und "03333" gültige Höhenzeichenfolgen.

Die Zeichenfolge "03333" stellt eine höhere Höhe als "100,123456" dar. (Führende und nachfolgende Nullen werden ignoriert.) Mit anderen Worten, eine Instanz, deren Höhe "03333" ist, ist weiter vom Basisdateisystem entfernt als eine Instanz, deren Höhe "100.123456" lautet. Dieser Vergleich ist jedoch nur dann sinnvoll, wenn beide Instanzen mit demselben Volume verbunden sind.

FltGetVolumeInstanceFromName fügt einen Rundownverweis auf den im RetInstance Parameter zurückgegebenen undurchsichtigen Instanzzeiger hinzu. Wenn dieser Zeiger nicht mehr benötigt wird, muss der Aufrufer ihn freigeben, indem FltObjectDereferenceaufgerufen wird. Daher muss jeder erfolgreiche Aufruf von FltGetVolumeInstanceFromName mit einem nachfolgenden Aufruf von FltObjectDereferenceabgeglichen werden.