FltGetUpperInstance-Funktion (fltkernel.h)

Artikel
02/26/2024

Die FltGetUpperInstance-Routine gibt einen undurchsichtigen instance-Zeiger für den nächsthöheren Minifiltertreiber zurück, instance, falls vorhanden, über einem bestimmten Minifiltertreiber instance auf demselben Volume angefügt ist.

Syntax

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

Parameter

[in] CurrentInstance

Undurchsichtiger instance Zeiger für die instance, für die der nächst höhere instance angefordert wird.

[out] UpperInstance

Zeiger auf eine vom Aufrufer zugewiesene Variable, die einen undurchsichtigen instance-Zeiger für den nächsthöheren instance empfängt. Dieser Parameter ist erforderlich und darf nicht NULL sein.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_NO_MORE_ENTRIES	Es wurde kein höherer instance gefunden. Dies ist ein Warncode.

Hinweise

Ein instance soll sich über dem anderen befinden, wenn es in einer höheren Höhe auf derselben Lautstärke angebracht ist. Der Begriff "Höhe" bezieht sich auf die Position, die ein instance im Minifiltertreiber instance Stapels für ein Volume einnimmt (oder belegen sollte). Je höher die Höhe, desto weiter ist die instance aus dem Basisdateisystem im Stapel. Nur eine instance kann in einer bestimmten Höhe auf einem bestimmten Volumen angebracht werden.

Die Höhe wird durch eine Höhenzeichenfolge angegeben, bei der es sich um eine gezählte Unicode-Zeichenfolge handelt, die aus einer oder mehreren Dezimalstellen im Bereich von 0 bis 9 besteht und einen einzelnen Dezimalpunkt enthalten kann. 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, ein instance dessen Höhe "0333" ist, ist weiter vom Basisdateisystem entfernt als ein instance dessen Höhe "100,123456" ist. Dieser Vergleich ist jedoch nur sinnvoll, wenn beide Instanzen an dasselbe Volume angefügt sind.

FltGetUpperInstance fügt einen Rundownverweis zum undurchsichtigen instance-Zeiger hinzu, der im UpperInstance-Parameter zurückgegeben wird. Wenn dieser Zeiger nicht mehr benötigt wird, muss der Aufrufer ihn freigeben, indem er FltObjectDereference aufruft. Daher muss jeder erfolgreiche Aufruf von FltGetUpperInstance durch einen nachfolgenden Aufruf von FltObjectDereference abgeglichen werden.