Freigeben über

Unterstützen von BypassEA-Vorgängen

  • Artikel

Ab Windows 11 sollten alle Minifilter Unterstützung für BypassIO-Vorgänge hinzufügen. BypassIO-Vorgänge werden durch Aufrufen von FltFsControlFile oder ZwFsControlFile mit:

  • Der FSCTL_MANAGE_BYPASS_IO Steuerelementcode.
  • Die anforderungsspezifischen Informationen in einer FS_BPIO_INPUT Struktur, auf die der InputBuffer-Parameter verweist.
  • Eine vom Aufrufer zugewiesene FS_BPIO_OUTPUT Struktur, auf die der OutputBuffer-Parameter verweist, in dem das System die Ergebnisse des Vorgangs zurückgibt.

Diese Seite enthält Details für jeden BypassIO-Vorgang. Die Vorgangsanforderung wird als FS_BPIO_OPERATIONS Wert im Operation-Element von FS_BPIO_INPUT angegeben.

Weitere Informationen zu BypassIO finden Sie unter BypassIO für Filter.

FS_BPIO_OP_ENABLE Anforderung

Diese Anforderung kann vom Benutzer- oder Kernelmodus stammen. BypassIO für nicht zwischengespeicherte Schreibvorgänge wird derzeit nicht unterstützt.

FS_BPIO_OP_ENABLE anforderungen, dass das System BypassIO für die angegebene Datei aktiviert, was bedeutet, dass ein Treiber möglicherweise nicht alle nicht zwischengespeicherten Lesevorgänge für diese Datei anzeigt.

BypassIO ist ein Konzept pro Datei öffnen; d. h. eine FS_BPIO_OP_ENABLE Anforderung wirkt sich nur auf das Dateiobjekt aus, das der Aktivierungsanforderung zugeordnet ist, und ändert nicht das Verhalten anderer Dateien oder Datenströme. Wenn mehrere Aktivierungsanforderungen an dasselbe Dateiobjekt gesendet werden, ist nur die erste Anforderung aussagekräftig, und alle nachfolgenden Anforderungen werden ignoriert.

Im Voroperationsrückruf des Treibers:

  • Wenn ein Treiber BypassIO für die angegebene Datei unterstützen kann, sollte er die Anforderung an den Stapel weiterleiten.

  • Wenn der Treiber BypassIO für die angegebene Datei nicht unterstützen kann, sollte fltVetoBypassIo mit den folgenden Informationen aufgerufen werden:

    • Der Name des Treibers, der sich in der FLT_RELATED_OBJECTS Struktur befindet, auf die der FltObjects-Parameter verweist.
    • Ein NTSTATUS-Fehlercode, der beschreibt, warum Sie die Enable-Anforderung im Parameter OperationStatus vetoing.
    • Eine eindeutige, beschreibende Zeichenfolge mit Details dazu, warum Sie die Enable-Anforderung im Parameter FailureReason vetoed haben.

    FltVetoBypassIo schreibt den Treibernamen, Fehlercode und die Zeichenfolge, die beschreibt, warum der Minifilter die Aktivierungsanforderung in der FS_BPIO_OUTPUT-Struktur vetoed hat und ein ETW-Ereignis mit dem Status, dem filterbasierten Grund und dem Namen des Filters in das Ereignisprotokoll schreibt.

Der Minifilter sollte FSCTL_MANAGE_BYPASS_IO mit STATUS_SUCCESS abschließen, wenn FltVetoBypassIo erfolgreich ist. Andernfalls sollte der Fehler zurückgegeben werden, den FltVetoBypassIo zurückgegeben hat.

Während des Vorgangs kann der Treiber sehen, ob alle darunter liegenden Treiber BypassIO unterstützen können. Wenn ja, sollte der Treiber den erforderlichen Zustand für die Datei beibehalten und die Verarbeitung der Fertigstellung fortsetzen. Es liegt in der Verantwortung des Filters und dateisystems, den Zustand beizubehalten, um Anforderungen ordnungsgemäß zu verarbeiten, die möglicherweise nicht mit dem Status "BypassIO-enabled" kompatibel sind.

Hinweis

Alle Filter im Dateisystemstapel haben die Möglichkeit, die BypassIO-Aktivierungsanforderung während des Vorvorgangs zu veto, aber empfohlen, sie so weit wie möglich aktiviert zu halten.

Das Dateisystem vetoiert automatisch eine BypassIO-Aktivierungsanforderung für die folgenden Dateitypen:

  • Verzeichnisse (alternative Datenströme in einem Verzeichnis können BypassIO verwenden)
  • Volumes (DASD wird geöffnet)
  • NTFS-komprimierte Dateien
  • NTFS-encryted files
  • Sparsedateien
  • Auslagerungsdateien
  • Alle Dateien auf DAX-Volumes

Die meisten Filter müssen nicht den Zustand beibehalten, dass BypassIO für einen bestimmten Datenstrom aktiviert wurde. Stattdessen können diese Informationen durch Aufrufen von FsRtlGetBypassIoOpenCount abgefragt werden.

FS_BPIO_OP_ENABLE Beispiel: Verschlüsselungsfilter

Wenn ein Verschlüsselungsfilter einen FS_BPIO_OP_ENABLE Vorgang für eine Datei empfängt:

  • Wenn die Datei bereits verschlüsselt ist, sollte der Filter FltVetoBypassIo aufrufen, um den BypassIO-Vorgang zu veto zu veto, um den entsprechenden Status und eine Diagnosenachricht bereitzustellen, z. B.:

    • OpStatus = STATUS_NOT_SUPPORTED_WITH_ENCRYPTION
    • FailureReason = "Verschlüsselte Datei nicht unterstützt"

  • Wenn die Datei derzeit nicht verschlüsselt ist, sollte der Filter BypassIO zulassen. Wenn eine spätere Anforderung zum Verschlüsseln dieser Datei erfolgt, kann der Filter den FS_BPIO_OP_STREAM_PAUSE Vorgang verwenden, um BypassIO zu deaktivieren.

FS_BPIO_OP_DISABLE Anforderung

Diese Anforderung kann vom Benutzer- oder Kernelmodus stammen. Er ermöglicht es einem Treiber, jeden zugeordneten BypassIO-Zustand zu bereinigen.

Wenn ein Treiber zuvor die Aktivierung von BypassIO für diese Datei zugelassen hat und nun die BypassIO-Unterstützung für eine Datei deaktivieren muss, sollte der FS_BPIO_OP_DISABLE FSCTL_MANAGE_BYPASS_IO Vorgang über dem Dateisystemstapel mithilfe des zugeordneten Handles an den Anfang des Dateisystemstapels gesendet werden. Ein Beispiel dafür, wann diese Bedingung auftreten kann, ist ein Verschlüsselungstreiber, der eine Anforderung zum Verschlüsseln dieser Datei erhalten hat.

Wenn ein Treiber FS_BPIO_OP_DISABLE empfängt, derzeit jedoch keine BypassIO aktiviert hat, sollte er die Anforderung ignorieren. Wenn dieser Vorgang für eine Datei gesendet wird, die derzeit nicht BypassIO aktiviert hat, sollte dieser ignoriert werden.

Dieser Vorgang sollte nicht fehlgeschlagen sein.

FS_BPIO_OP_QUERY Anforderung

Diese Anforderung kann vom Benutzer- oder Kernelmodus stammen.

Ein Filter sollte eine FS_BPIO_OP_QUERY Anforderung verarbeiten, die einem FS_BPIO_OP_ENABLE Vorgang ähnelt, wobei FltVetoBypassIo entsprechend mit den gleichen Diagnoseinformationen wie zuvor in den entsprechenden Parametern beschrieben veto aufgerufen wird. Der Hauptunterschied besteht darin, dass der Treiber während einer ABFRAGE nicht in den BypassIO ENABLE-Zustand wechselt.

Der vorgang FS_BPIO_OP_QUERY kann auf Verzeichnis- und Volumehandles gesendet werden (eine FS_BPIO_OP_ENABLE Anforderung kann nicht auf Verzeichnis- oder Volumehandles gesendet werden).

Abfragebeispiel: Verschlüsselungsfilter

Wenn ein Verschlüsselungsfilter einen FS_BPIO_OP_QUERY Vorgang für eine Datei empfängt:

  • Wenn die Datei bereits verschlüsselt ist, sollte der Filter FltVetoBypassIo aufrufen, um den BypassIO-Vorgang zu veto, und es wird ein entsprechender Status und eine entsprechende Diagnosenachricht bereitgestellt, z. B.:

    • OpStatus = STATUS_NOT_SUPPORTED_WITH_ENCRYPTION
    • FailureReason = "Verschlüsselte Datei nicht unterstützt"

  • Wenn die Datei derzeit nicht verschlüsselt ist, sollte der Filter die Abfrageanforderung erfolgreich ausführen.

FS_BPIO_OP_VOLUME_STACK_PAUSE Anforderung

Diese Anforderung kann vom Benutzer- oder Kernelmodus stammen.

Wenn ein Volumestapeltreiber zuvor die Aktivierung von BypassIO auf einem Volume erlaubt hat und nun BypassIO beenden muss (z. B. aufgrund einer externen Anforderung), sollte der Treiber einen FS_BPIO_OP_VOLUME_STACK_PAUSE FSCTL_MANAGE_BYPASS_IO Vorgang an den Anfang des Volumestapels senden, um das Dateisystem zu benachrichtigen, damit BypassIO auf dem Volume und den Speicherstapel dieses Volumes beendet wird. Das Dateisystem entfällt alle aktiven BypassIO-Vorgänge von diesem Volume und gibt dann zurück. Der Volumestapeltreiber kann dann die externe Anforderung verarbeiten.

Alle aktiven BypassIO-fähigen Dateien beenden dann die Ausführung von BypassIO-Vorgängen auf Speicherstapelebene. Diese Vorgangsanforderung:

  • Kann auf einem Volumehandle oder einem beliebigen Dateihandle für das angegebene Volume gesendet werden.
  • Kann mehrmals an dasselbe Volume gesendet werden.
  • Kann gesendet werden, wenn keine BypassIO-fähigen Dateien auf dem Volume vorhanden sind.

BypassIO wird weiterhin auf dem Dateisystemstapel ausgeführt.

Dieser Vorgang sollte nicht fehlgeschlagen sein.

Beispiel für die Unterbrechung des Volumestapels

BitLocker ist ein Beispiel für eine Komponente, die diesen Vorgang verwendet, wenn sie die Verschlüsselung auf einem Volume aktivieren muss.

Ein weiteres Beispiel ist das folgende Szenario: Angenommen, Volsnap erlaubte BypassIO auf einem Volume zu aktivieren, für das keine aktiven Volumemomentaufnahmen vorhanden waren. Später wurde eine Anforderung zum Erstellen einer Volumemomentaufnahme gestellt. Volsnap führt die folgenden Aktionen aus, bevor Sie fortfahren:

  • Sendet den FS_BPIO_OP_VOLUME_STACK_PAUSE Vorgang an den Anfang des Stapels, der anfordert, dass das System BypassIO auf dem Volumestapel deaktiviert. Dies geschieht jedes Mal, wenn eine neue Momentaufnahme erstellt wird. Bei erfolgreicher Rückgabe wird BypassIO jetzt deaktiviert und auf das angegebene Volume entwässert.
  • Verarbeitet die Erstellungsanforderung für Momentaufnahmen

Volsnap muss dann alle zukünftigen BPIO_OP_ENABLE und BPIO_OP_QUERY Anforderungen an dieses Volume veto.

FS_BPIO_OP_VOLUME_STACK_RESUME Anforderung

Ein Volumestapeltreiber sendet diesen FSCTL-Vorgang an das Dateisystem, um die BypassIO-Verarbeitung auf dem angegebenen Volume fortzusetzen. Dieser Vorgang wird gesendet, wenn das Szenario, das dazu führte, dass der Treiber FS_BPIO_OP_VOLUME_STACK_PAUSE gesendet hat, nicht mehr aktiv ist. Dieser Vorgang kann auch gesendet werden, wenn BypassIO derzeit nicht aktiviert oder angehalten ist.

Diese Anforderung kann vom Benutzer- oder Kernelmodus stammen.

Dieser Vorgang sollte nicht fehlgeschlagen sein.

Beispiel für den Lebenslauf des Volumestapels

Wenn Sie das zuvor beschriebene Szenario für die Volumestapel-Pause verwenden, gibt es keine aktiven Momentaufnahmen mehr. Volsnap sendet FS_BPIO_OP_VOLUME_STACK_RESUME erst, nachdem die letzte Momentaufnahme entfernt wurde.

FS_BPIO_OP_STREAM_PAUSE Anforderung

Ein Filter kann einen FS_BPIO_OP_STREAM_PAUSE Vorgang senden, um BypassIO in einem Datenstrom anzuhalten. Diese Anforderung kann vom Benutzer- oder Kernelmodus stammen. Alle aktiven BypassIO-fähigen Dateien beenden die BypassIO-Vorgänge.

Wenn ein Filter zuvor die Aktivierung von BypassIO für einen Datenstrom erlaubt hat und später BypassIO beenden muss (aufgrund einer externen Anforderung, z. B. einer Anforderung zum Verschlüsseln einer Datei oder eines Verzeichnisses), kann ein FS_BPIO_OP_STREAM_PAUSE den Filterstapel nach unten senden, um dem Dateisystem mitzuteilen, dass BypassIO für den angegebenen Datenstrom beendet wird. Ein Filter sollte diesen Vorgang nicht an den Anfang des Stapels senden.

Bevor das Dateisystem zurückkehrt, hält es alle BypassIO-Handles an, die im Datenstrom geöffnet sind, und schließt alle aktiven BypassIO-Vorgänge im Datenstrom ab. Diese Aktionen stellen sicher, dass der Filter beim Zurückgeben den erforderlichen Dateivorgang ausführen kann.

Dieser Vorgang kann mehrmals an denselben Datenstrom gesendet werden. Das Dateisystem ignoriert sie, wenn es in einem Stream gesendet wird, der derzeit nicht BypassIO-aktiviert ist.

Wenn ein Filter einen Datenstrom-Pausenvorgang durchführt, wird BypassIO auf dem Volume und den Speicherstapeln fortgesetzt.

Dieser Vorgang sollte nicht fehlgeschlagen sein.

Stream pause example: encryption filter

Angenommen, ein Verschlüsselungsfilter erlaubte BypassIO für einen Datenstrom zu aktivieren, der nicht verschlüsselt wurde, aber später eine Anforderung zum Verschlüsseln dieses Datenstroms erhalten hat.

Bevor der Verschlüsselungsfilter fortgesetzt wird, sollte fsRtlGetBypassIoOpenCount aufgerufen werden, um festzustellen, ob BypassIO für diesen Stream aktiv ist. Wenn ja, sendet der Verschlüsselungsfilter einen FS_BPIO_OP_STREAM_PAUSE Vorgang, der fragt, ob das System BypassIO deaktiviert. Bei erfolgreicher Rückgabe wird BypassIO deaktiviert und entwässert, sodass der Filter die Verschlüsselungsanforderung sicher ausführen kann. Um mögliche Rennbedingungen zu beseitigen, muss der Filter alle zukünftigen FS_BPIO_OP_ENABLE und FS_BPIO_OP_QUERY Anforderungen für diesen jetzt verschlüsselten Datenstrom vetoieren.

FS_BPIO_OP_STREAM_RESUME Anforderung

Wenn das Szenario, in dem der Filter zum Senden eines FS_BPIO_OP_STREAM_PAUSE Vorgangs führte, nicht mehr vorhanden ist, sendet der Filter einen FS_BPIO_OP_STREAM_RESUME Vorgang an das Dateisystem, um die BypassIO-Verarbeitung eines bestimmten Datenstroms fortzusetzen. Diese Anforderung kann vom Benutzer- oder Kernelmodus stammen.

Wenn dieser Vorgang gesendet wird, wenn BypassIO derzeit nicht aktiviert oder angehalten ist, wird er ignoriert.

Anhalten und Fortsetzen werden nicht gezählt. Stattdessen gibt das Dateisystem bei einem Lebenslauf eine FS_BPIO_OP_QUERY Anforderung am Anfang des Dateisystemstapels aus, um festzustellen, ob noch verbleibende Filter blockiert werden. Das Dateisystem setzt BypassIO nur dann fort, wenn alle Filter im Stapel BypassIO nicht blockieren.

Dieser Vorgang sollte nicht fehlgeschlagen sein.

Beispiel für den Stream-Lebenslauf: Verschlüsselungsfilter

Wenn Sie das zuvor beschriebene szenario FS_BPIO_OP_STREAM_PAUSE verwenden, sagen Sie, dass die Datei, die zuvor nach dem Aufruf von FS_BPIO_OP_STREAM_PAUSE verschlüsselt wurde, nicht mehr verschlüsselt ist. Der Filter sollte dann den FS_BPIO_OP_STREAM_RESUME-Vorgang senden, damit BypassIO in diesem Datenstrom fortgesetzt werden kann.

FS_BPIO_OP_GET_INFO Anforderung

Diese Anforderung kann vom Benutzer- oder Kernelmodus stammen. Das Dateisystem gibt Informationen über BypassIO für das Volume in einer FS_BPIO_INFO-Struktur zurück.