FltGetTopInstance-Funktion (fltkernel.h)

Artikel
08/07/2023

Die FltGetTopInstance-Routine gibt einen undurchsichtigen instance Zeiger für den Minifiltertreiber instance zurück, der am oberen Rand des instance stapels 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 instance Zeiger für den unteren instance für dieses Volume empfängt. Dieser Parameter ist erforderlich und darf nicht NULL sein.

Rückgabewert

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

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

Hinweise

Ein instance soll sich am oberen Rand des Minifiltertreibers instance Stapels befinden, wenn seine Höhe höher als die aller anderen Instanzen ist, die an dasselbe Volume angefügt sind. Der Begriff "Höhe" bezieht sich auf die Position, die ein instance im Minifiltertreiber instance Stapel für ein Volume einnimmt. Je höher die Höhe, desto weiter ist die instance vom Basisdateisystem im Stapel entfernt. Nur ein instance kann in einer bestimmten Höhe auf einem bestimmten Volume 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 von 0 bis 9 besteht und ein einzelnes Dezimaltrennzeichen 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.) Anders ausgedrückt: Ein instance dessen Höhe "03333" 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.

FltGetTopInstance fügt einen Rundownverweis auf den undurchsichtigen instance-Zeiger hinzu, der im Instance-Parameter zurückgegeben wird. Wenn dieser Zeiger nicht mehr benötigt wird, muss der Aufrufer ihn durch Aufrufen von FltObjectDereference freigeben. Daher muss jeder erfolgreiche Aufruf von FltGetTopInstance durch einen nachfolgenden Aufruf von FltObjectDereference abgeglichen werden.