FltGetTopInstance-Funktion (fltkernel.h)

Artikel
02/06/2025

Die FltGetTopInstance Routine gibt einen undurchsichtigen Instanzzeiger für die Minifiltertreiberinstanz zurück, die am oberen Rand des Instanzstapels für ein bestimmtes Volume angefügt ist.

Syntax

NTSTATUS FLTAPI FltGetTopInstance(
  [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

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

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 oberen des Minifilter-Treiberinstanzstapels befindet, wenn ihre Höhe höher 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.

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