FltGetLowerInstance-Funktion (fltkernel.h)

Artikel
02/06/2025

Die FltGetLowerInstance Routine gibt einen undurchsichtigen Instanzzeiger für die nächste untere Minifiltertreiberinstanz zurück, falls vorhanden, die unter einer bestimmten Minifiltertreiberinstanz auf demselben Volume angefügt ist.

Syntax

NTSTATUS FLTAPI FltGetLowerInstance(
  [in]  PFLT_INSTANCE CurrentInstance,
  [out] PFLT_INSTANCE *LowerInstance
);

Parameter

[in] CurrentInstance

Undurchsichtiger Instanzzeiger für die Minifiltertreiberinstanz, für die die niedrigere Minifiltertreiberinstanz angefordert wird.

[out] LowerInstance

Zeiger auf eine vom Aufrufer zugewiesene Variable, die einen undurchsichtigen Minifilter-Treiberinstanzzeiger für die nächste niedrigere Minifiltertreiberinstanz empfängt. Dieser Parameter ist erforderlich und kann nicht NULL-werden.

Rückgabewert

FltGetLowerInstance gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert zurück, z. B. folgendes:

Rückgabecode	Beschreibung
STATUS_NO_MORE_ENTRIES	Es wurde keine niedrigere Minifiltertreiberinstanz gefunden. Dies ist ein Warncode.

Bemerkungen

Eine Instanz soll unter anderen sein, wenn sie auf einer niedrigeren Höhe auf demselben Volumen angeschlossen ist. 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.

FltGetLowerInstance fügt einen Rundownverweis auf den im LowerInstance 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 FltGetLowerInstance mit einem nachfolgenden Aufruf von FltObjectDereferenceabgeglichen werden.