FltGetUpperInstance-Funktion (fltkernel.h)

Artikel
02/06/2025

Die FltGetUpperInstance Routine gibt einen undurchsichtigen Instanzzeiger für die nächste höhere Minifiltertreiberinstanz zurück, falls vorhanden, die oberhalb einer bestimmten Minifiltertreiberinstanz auf demselben Volume angefügt wird.

Syntax

NTSTATUS FLTAPI FltGetUpperInstance(
  [in]  PFLT_INSTANCE CurrentInstance,
  [out] PFLT_INSTANCE *UpperInstance
);

Parameter

[in] CurrentInstance

Undurchsichtiger Instanzzeiger für die Instanz, für die die nächste höhere Instanz angefordert wird.

[out] UpperInstance

Zeiger auf eine vom Aufrufer zugewiesene Variable, die einen undurchsichtigen Instanzzeiger für die nächste höhere Instanz empfängt. Dieser Parameter ist erforderlich und kann nicht NULL-werden.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_NO_MORE_ENTRIES	Es wurde keine höhere Instanz gefunden. Dies ist ein Warncode.

Bemerkungen

Es wird davon gesprochen, dass eine Instanz über einer anderen wird, wenn sie in einer höheren 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 im Bereich 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.

FltGetUpperInstance fügt einen Rundown-Verweis auf den undurchsichtigen Instanzzeiger hinzu, der im parameter UpperInstance 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 FltGetUpperInstance durch einen nachfolgenden Aufruf von FltObjectDereferenceabgeglichen werden.