FltAttachVolumeAtAltitude-Funktion (fltkernel.h)

Artikel
08/07/2023

FltAttachVolumeAtAltitude ist eine Debugunterstützungsroutine, die einen Minifiltertreiber instance an ein Volume in einer angegebenen 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 darf nicht NULL sein.

[in, out] Volume

Undurchsichtiger Volumezeiger für das Volume, an das der Minifiltertreiber instance angefügt werden soll. Dieser Parameter ist erforderlich und darf nicht NULL sein.

[in] Altitude

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

[in, optional] InstanceName

Zeiger auf eine UNICODE_STRING-Struktur, die den instance Namen für die neue instance enthält. Dieser Parameter ist optional und kann NULL sein. Wenn es NULL ist, generiert FltAttachVolumeAtAltitude einen instance Namen aus dem Namen des Minifiltertreibers und der Höhenzeichenfolge, auf die Höhe zeigt. Der generierte Name wird bei Bedarf abgeschnitten, um Zeichen zu INSTANCE_NAME_MAX_CHARS.

[out, optional] RetInstance

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

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_FLT_DELETING_OBJECT	Der angegebene Filter oder das angegebene Volume wird abgerissen. Dies ist ein Fehlercode.
STATUS_FLT_FILTER_NOT_READY	Der Minifiltertreiber hat die Filterung nicht gestartet. Weitere Informationen finden Sie unter FltStartFiltering. Dies ist ein Fehlercode.
STATUS_FLT_INSTANCE_ALTITUDE_COLLISION	Ein instance in dieser Höhe auf der angegebenen Lautstärke bereits vorhanden. Dies ist ein Fehlercode.
STATUS_FLT_INSTANCE_NAME_COLLISION	Auf dem angegebenen Volume ist bereits eine instance mit diesem Namen vorhanden. Dies ist ein Fehlercode.
STATUS_INSUFFICIENT_RESOURCES	Bei FltAttachVolumeAtAltitude ist ein Poolzuordnungsfehler aufgetreten. Dies ist ein Fehlercode.
STATUS_INVALID_PARAMETER	Die UNICODE_STRING Struktur, auf die Höhe zeigt, enthielt keine gültige Höhenzeichenfolge. Dies ist ein Fehlercode.

Hinweise

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-Funktion FilterAttachAtAltitude .

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 ein Breitzeichenarray handelt, das eine oder mehrere Dezimalstellen von 0 bis 9 enthält; das Array kann ein einzelnes Dezimaltrennzeichen 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.) 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.

Der im Parameter InstanceName angegebene instance Name muss im gesamten System eindeutig sein.

FltAttachVolumeAtAltitude gibt einen undurchsichtigen instance Zeiger für die neue instance in *RetInstance zurück. Dieser Zeigerwert identifiziert eindeutig den Minifiltertreiber instance und bleibt konstant, solange der instance an das Volume angefügt ist.

FltAttachVolumeAtAltitude fügt einen Rundownverweis auf den in *RetInstance zurückgegebenen undurchsichtigen instance-Zeiger hinzu. Wenn dieser Zeiger nicht mehr benötigt wird, muss der Aufrufer ihn durch Aufrufen von FltObjectDereference freigeben. Daher muss jeder erfolgreiche Aufruf von FltAttachVolumeAtAltitude durch einen nachfolgenden Aufruf von FltObjectDereference abgeglichen werden.

Rufen Sie FltCompareInstanceAltitudes auf, um die Höhe von zwei Minifiltertreiberinstanzen zu vergleichen, die an dasselbe Volume angefügt sind.

Um einen Minifiltertreiber instance von einem Volume zu trennen, rufen Sie FltDetachVolume auf.