FltGetVolumeInstanceFromName-Funktion (fltkernel.h)

Artikel
02/29/2024

Die FltGetVolumeInstanceFromName-Routine gibt einen undurchsichtigen instance Zeiger für den angegebenen Minifiltertreiber instance auf dem angegebenen Volume zurück.

Syntax

NTSTATUS FLTAPI FltGetVolumeInstanceFromName(
  [in, optional] PFLT_FILTER      Filter,
  [in]           PFLT_VOLUME      Volume,
  [in, optional] PCUNICODE_STRING InstanceName,
  [out]          PFLT_INSTANCE    *RetInstance
);

Parameter

[in, optional] Filter

Undurchsichtiger Filterzeiger für den Minifiltertreiber, der den instance besitzt. Dieser Parameter ist optional und kann NULL sein.

[in] Volume

Undurchsichtiger Zeiger für das Volume, an das die instance angefügt ist. Muss ein gültiges Volumehandle sein. Dieser Parameter ist erforderlich und darf nicht NULL sein. (Wenn Dieser Parameter auf einen ungültigen Wert festgelegt wird, wird das System für einen überprüften Build assert.)

[in, optional] InstanceName

Zeiger auf eine vom Aufrufer zugewiesene UNICODE_STRING-Struktur, die den instance Namen für die instance auf dem Volume enthält. (Dies ist der InstanceName-Wert, der beim Erstellen des instance an FltAttachVolume oder FltAttachVolumeAtAltitude übergeben wurde.) Dieser Parameter ist optional und kann NULL sein. Wenn es NULL ist, gibt FltGetVolumeInstanceFromName den höchsten übereinstimmenden instance zurück, der gefunden wird.

[out] RetInstance

Zeiger auf eine vom Aufrufer zugewiesene Variable, die einen undurchsichtigen instance Zeiger für die instance empfängt, die den Werten für Filter, Volume und Instanzname entspricht. Dieser Parameter ist erforderlich und darf nicht NULL sein.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_FLT_DELETING_OBJECT	Die instance wird abgerissen. Dies ist ein Fehlercode.
STATUS_FLT_INSTANCE_NOT_FOUND	Es wurde keine übereinstimmende instance gefunden. Dies ist ein Fehlercode.

Hinweise

FltGetVolumeInstanceFromName durchsucht die Liste der Minifiltertreiberinstanzen, die an das im Volume-Parameter angegebene Volume angefügt sind, in der Reihenfolge der abnehmenden Höhe, beginnend mit dem obersten instance. Wenn mehrere instance mit den angegebenen Werten für die Parameter Filter, Volume und InstanceName übereinstimmen, gibt FltGetVolumeInstanceFromName den höchsten übereinstimmenden instance zurück, der gefunden wird.

Der Begriff "Höhe" bezieht sich auf die Position, die ein instance im Minifiltertreiber instance Stapel für ein Volume einnimmt (oder belegen sollte). 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.

FltGetVolumeInstanceFromName fügt einen Rundownverweis auf den undurchsichtigen instance-Zeiger hinzu, der im RetInstance-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 FltGetVolumeInstanceFromName durch einen nachfolgenden Aufruf von FltObjectDereference abgeglichen werden.