FltAttachVolumeAtAltitude-Funktion (fltkernel.h)

Artikel
02/06/2025

FltAttachVolumeAtAltitude ist eine Debugunterstützungsroutine, die eine Minifiltertreiberinstanz an ein Volume in einer bestimmten Höhe anfügt und alle Einstellungen in der INF-Datei des Minifiltertreibers überschreibt.

Syntax

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

Parameter

[in, out] Filter

Undurchsichtiger Filterzeiger für den Aufrufer. Dieser Parameter ist erforderlich und kann nicht NULL-werden.

[in, out] Volume

Undurchsichtiger Volumezeiger für das Volume, an das die Minifiltertreiberinstanz angefügt werden soll. Dieser Parameter ist erforderlich und kann nicht NULL-werden.

[in] Altitude

Zeigen Sie auf eine UNICODE_STRING Struktur, die die Höhenzeichenfolge für die Instanz enthält. Dieser Parameter ist erforderlich und kann nicht NULL-werden. (Weitere Informationen zu diesem Parameter finden Sie im folgenden Abschnitt "Hinweise".)

[in, optional] InstanceName

Zeigen Sie auf eine UNICODE_STRING Struktur, die den Instanznamen für die neue Instanz enthält. Dieser Parameter ist optional und kann NULL-werden. Wenn es NULL-ist, generiert FltAttachVolumeAtAltitude einen Instanznamen aus dem Namen des Minifiltertreibers und der Höhenzeichenfolge, auf die Altitude verweist. Der generierte Name wird ggf. abgeschnitten, um Zeichen zu INSTANCE_NAME_MAX_CHARS.

[out, optional] RetInstance

Zeiger auf eine vom Aufrufer zugewiesene Variable, die einen undurchsichtigen Instanzzeiger für die neu erstellte Instanz empfängt. Dieser Parameter ist optional und kann NULL-werden.

Rückgabewert

FltAttachVolumeAtAltitude gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert wie einen der folgenden zurück:

Rückgabecode	Beschreibung
STATUS_FLT_DELETING_OBJECT	Der angegebene Filter- oder Volume- wird heruntergerissen. Dies ist ein Fehlercode.
STATUS_FLT_FILTER_NOT_READY	Der Minifiltertreiber hat nicht mit dem Filtern begonnen. Weitere Informationen finden Sie unter FltStartFiltering. Dies ist ein Fehlercode.
STATUS_FLT_INSTANCE_ALTITUDE_COLLISION	Eine Instanz ist bereits in dieser Höhe auf dem angegebenen Volume vorhanden. Dies ist ein Fehlercode.
STATUS_FLT_INSTANCE_NAME_COLLISION	Eine Instanz ist bereits mit diesem Namen auf dem angegebenen Volume vorhanden. Dies ist ein Fehlercode.
STATUS_INSUFFICIENT_RESOURCES	FltAttachVolumeAtAltitude ein Poolzuordnungsfehler aufgetreten ist. Dies ist ein Fehlercode.
STATUS_INVALID_PARAMETER	Die UNICODE_STRING Struktur, die Höhe Punkte keine gültige Höhenzeichenfolge enthält. Dies ist ein Fehlercode.

Bemerkungen

Ein Minifiltertreiber sollte nur FltAttachVolumeAtAltitude- zum Debuggen verwenden. Diese Routine sollte nicht in einer Einzelhandelsversion des Minifiltertreibers aufgerufen werden.

FltAttachVolumeAtAltitude ist das Kerneläquivalent der Win32-FilterAttachAtAltitude Funktion.

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, bei der es sich um ein Breitzeichenarray handelt, das eine oder mehrere Dezimalziffern zwischen 0 und 9 enthält; das Array kann einen einzelnen Dezimalkomma 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.

Der im InstanceName Parameter angegebene Instanzname muss im gesamten System eindeutig sein.

FltAttachVolumeAtAltitude gibt einen undurchsichtigen Instanzzeiger für die neue Instanz in *RetInstancezurück. Dieser Zeigerwert identifiziert die Minifiltertreiberinstanz eindeutig und bleibt konstant, solange die Instanz an das Volume angefügt ist.

FltAttachVolumeAtAltitude fügt einen Rundownverweis auf den in *RetInstancezurückgegebenen undurchsichtigen Instanzzeiger hinzu. Wenn dieser Zeiger nicht mehr benötigt wird, muss der Aufrufer ihn freigeben, indem FltObjectDereferenceaufgerufen wird. Daher muss jeder erfolgreiche Aufruf von FltAttachVolumeAtAltitude durch einen nachfolgenden Aufruf von FltObjectDereferenceabgeglichen werden.

Rufen Sie FltCompareInstanceAltitudesauf, um die Höhe von zwei Minifiltertreiberinstanzen zu vergleichen, die mit demselben Volume verbunden sind.

Rufen Sie FltDetachVolumeauf, um eine Minifiltertreiberinstanz von einem Volume zu trennen.