FltGetBottomInstance-Funktion (fltkernel.h)

Artikel
02/06/2025

FltGetBottomInstance gibt einen undurchsichtigen Instanzzeiger für die Minifiltertreiberinstanz zurück, falls vorhanden, die am unteren Rand des Instanzstapels für ein bestimmtes Volume angefügt ist.

Syntax

NTSTATUS FLTAPI FltGetBottomInstance(
  [in]  PFLT_VOLUME   Volume,
  [out] PFLT_INSTANCE *Instance
);

Parameter

[in] Volume

Undurchsichtiger Zeiger für das Volume.

[out] Instance

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

Rückgabewert

FltGetBottomInstance gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert wie den folgenden zurück:

Rückgabecode	Beschreibung
STATUS_NO_MORE_ENTRIES	Es wurde keine übereinstimmende Instanz gefunden. Dies ist ein Warncode.

Bemerkungen

Es wird gesagt, dass sich eine Instanz am unteren des Minifilter-Treiberinstanzstapels befindet, wenn die Höhe niedriger als die aller anderen Instanzen ist, die mit demselben Volume verbunden sind. Der Begriff "Höhe" bezieht sich auf die Position, die eine Instanz im Minifilter-Treiberinstanzstapel für ein Volume belegt. 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.

FltGetBottomInstance fügt einen Rundownverweis auf den undurchsichtigen Instanzzeiger hinzu, der in *Instancezurückgegeben wird. Wenn dieser Zeiger nicht mehr benötigt wird, muss der Aufrufer ihn freigeben, indem FltObjectDereferenceaufgerufen wird. Daher muss jeder erfolgreiche Aufruf von FltGetBottomInstance durch einen nachfolgenden Aufruf von FltObjectDereferenceabgeglichen werden.