支援 BypassIO 作業

從 Windows 11 開始，所有迷你篩選都應該新增 BypassIO 作業的支援。 透過呼叫 FltFsControlFile 或 ZwFsControlFile 來要求 BypassIO 作業：

• FSCTL_MANAGE_BYPASS_IO控件程式代碼。
• InputBuffer 參數指向FS_BPIO_INPUT結構中的要求特定資訊。
• OutputBuffer 參數所指向的呼叫端配置FS_BPIO_OUTPUT結構，其中系統會傳回作業的結果。

此頁面提供每個 BypassIO 作業的詳細數據。 作業要求會指定為 FS_BPIO_INPUT 的 Operation 成員中的FS_BPIO_OPERATIONS值。

如需 BypassIO 的詳細資訊，請參閱 Filters 的 BypassIO。

FS_BPIO_OP_ENABLE要求

此要求可能來自使用者或核心模式。 目前不支援非快 取寫入 的 BypassIO。

FS_BPIO_OP_ENABLE要求系統為指定的檔案啟用 BypassIO，這表示驅動程式可能不會看到該檔案的所有非快取讀取。

BypassIO 是每個檔案開啟的概念;也就是說， FS_BPIO_OP_ENABLE 要求只會影響與啟用要求相關聯的檔案物件，而且不會變更相同檔案或數據流上其他開啟的行為。 如果傳送對相同檔案物件的多個啟用要求，則只有第一個要求有意義，而且會忽略所有後續要求。

在驅動程式的預先操作回呼中：

• 如果驅動程式可以支援指定檔案的 BypassIO，它應該將要求轉送至堆疊。

• 如果驅動程式不支援指定檔案的 BypassIO，它應該使用下列資訊呼叫 FltVetoBypassIo：

  • 驅動程式的名稱，位於 FltObjects 參數指向的FLT_RELATED_OBJECTS結構中。
  • NTSTATUS 錯誤碼，描述您在 OperationStatus 參數中否決啟用要求的原因。
  • 唯一的描述性字串，其中包含您在 FailureReason 參數中否決啟用要求的原因。

  FltVetoBypassIo 會寫入驅動程式名稱、錯誤碼和字串，描述小型篩選程式在FS_BPIO_OUTPUT結構中否決啟用要求的原因，並寫入具有狀態、篩選提供原因和篩選名稱的 ETW 事件至事件記錄檔。

如果 FltVetoBypassIo 成功，迷你篩選程式應該完成FSCTL_MANAGE_BYPASS_IO STATUS_SUCCESS;否則應該傳回 FltVetoBypassIo 傳回的錯誤。

在作業後期間，驅動程式可以看到其下方的所有驅動程式是否都能夠支援 BypassIO。 如果是，驅動程式應該保留檔案的任何必要狀態，並繼續完成處理。 篩選條件和文件系統負責維護狀態，以正確處理可能與啟用 BypassIO 狀態不相容的要求。

注意

文件系統堆疊中的所有篩選都有機會在預先操作期間否決 BypassIO 啟用要求，但建議您儘可能啟用它。

檔案系統會自動否決下列檔案類型的 BypassIO 啟用要求：

• 目錄（目錄上的替代資料流可以使用 BypassIO）
• 磁碟區 （DASD 開啟）
• NTFS 壓縮檔案
• NTFS 加密的檔案
• 疏鬆檔案
• 分頁檔
• DAX 磁碟區上的所有檔案

大部分篩選不需要維護在特定數據流上啟用 BypassIO 的狀態。 相反地，您可以呼叫 FsRtlGetBypassIoOpenCount 來查詢這項資訊。

FS_BPIO_OP_ENABLE範例：加密篩選

當加密篩選器在檔案上收到 FS_BPIO_OP_ENABLE 作業時：

• 如果檔案已經加密，篩選條件應該呼叫 FltVetoBypassIo 來否決 BypassIO 作業，並提供適當的狀態和診斷訊息，例如：

  • OpStatus = STATUS_NOT_SUPPORTED_WITH_ENCRYPTION
  • FailureReason = “不支援加密的檔案”

• 如果檔案目前未加密，篩選應該允許 BypassIO。 如果稍後要求加密此檔案，篩選條件可以使用 FS_BPIO_OP_STREAM_PAUSE 作業來停用 BypassIO。

FS_BPIO_OP_DISABLE要求

此要求可能來自使用者或核心模式。 它可讓驅動程式清除任何相關聯的 BypassIO 狀態。

如果驅動程式先前允許在此檔案上啟用 BypassIO，且現在需要關閉檔案的 BypassIO 支援，它應該使用相關聯的句柄，將FS_BPIO_OP_DISABLE FSCTL_MANAGE_BYPASS_IO作業傳送至文件系統堆疊的頂端。 發生此狀況的範例是收到加密此檔案要求的加密驅動程式。

如果驅動程式收到 FS_BPIO_OP_DISABLE 但目前未啟用 BypassIO，則應該忽略要求。 如果這項作業是在目前未啟用 BypassIO 的檔案上傳送，則應該忽略它。

此作業不應該失敗。

FS_BPIO_OP_QUERY要求

此要求可能來自使用者或核心模式。

篩選條件應該處理類似FS_BPIO_OP_ENABLE作業的FS_BPIO_OP_QUERY要求，並呼叫 FltVetoBypassIo，以與先前所述的診斷資訊一樣適當地否決。 主要差異在於驅動程式不會在 QUERY 期間進入 BypassIO ENABLE 狀態。

FS_BPIO_OP_QUERY作業可以在目錄和磁碟區句柄上傳送（無法在目錄或磁碟區句柄上傳送FS_BPIO_OP_ENABLE要求）。

查詢範例：加密篩選

當加密篩選器在檔案上收到 FS_BPIO_OP_QUERY 作業時：

• 如果檔案已經加密，篩選條件應該呼叫 FltVetoBypassIo 來否決 BypassIO 作業，並提供適當的狀態和診斷訊息，例如：

  • OpStatus = STATUS_NOT_SUPPORTED_WITH_ENCRYPTION
  • FailureReason = “不支援加密的檔案”

• 如果檔案目前未加密，篩選條件應該會成功查詢要求。

FS_BPIO_OP_VOLUME_STACK_PAUSE要求

此要求可能來自使用者或核心模式。

如果磁碟區堆疊驅動程式先前允許在磁碟區上啟用 BypassIO，而現在需要停止 BypassIO（例如，由於某些外部要求），驅動程式應該將FS_BPIO_OP_VOLUME_STACK_PAUSE FSCTL_MANAGE_BYPASS_IO作業傳送至磁碟區堆疊頂端，以通知文件系統停止在此磁碟區的磁碟區和儲存堆疊上執行 BypassIO。 檔案系統會從此磁碟區清空所有作用中的 BypassIO 作業，然後傳回 。 然後，磁碟區堆疊驅動程式可以處理外部要求。

所有已啟用 BypassIO 的作用中檔案，然後停止執行記憶體堆疊層級的 BypassIO 作業。 此工作要求：

• 可以在磁碟區句柄或任何指定磁碟區的檔案句柄上傳送。
• 可以多次傳送至相同的磁碟區。
• 如果磁碟區上沒有已啟用 BypassIO 的檔案，則可以傳送。

BypassIO 會繼續在文件系統堆疊上運作。

此作業不應該失敗。

磁碟區堆疊暫停範例

BitLocker 是元件範例，該元件需要啟用磁碟區上的加密時，會使用此作業。

另一個範例是下列案例：假設 Volsnap 允許在沒有作用中磁碟區快照集的磁碟區上啟用 BypassIO。 之後，已提出建立磁碟區快照集的要求。 Volsnap 會先執行下列動作，再繼續進行：

• 將 FS_BPIO_OP_VOLUME_STACK_PAUSE 作業傳送至要求系統停用磁碟區堆疊上 BypassIO 的堆疊頂端。 每次建立新的快照集時，都會執行此工作。 成功傳回時，現在會停用 BypassIO，並在指定的磁碟區上清空。
• 處理快照集建立要求

然後，Volsnap 必須否決此磁碟區上所有未來的 BPIO_OP_ENABLE 和 BPIO_OP_QUERY 要求。

FS_BPIO_OP_VOLUME_STACK_RESUME要求

磁碟區堆疊驅動程式會將此 FSCTL 作業傳送至文件系統，以在指定的磁碟區上繼續 BypassIO 處理。 當導致驅動程式傳送FS_BPIO_OP_VOLUME_STACK_PAUSE不再作用中的案例時，它會傳送這項作業。 即使目前未啟用或暫停 BypassIO，仍可傳送此作業。

此要求可能來自使用者或核心模式。

此作業不應該失敗。

磁碟區堆疊繼續範例

使用先前所述的磁碟區堆疊暫停案例，表示磁碟區不再有任何作用中的快照集。 只有在最後一個快照集消失之後，Volsnap 才會傳送 FS_BPIO_OP_VOLUME_STACK_RESUME 。

FS_BPIO_OP_STREAM_PAUSE要求

篩選條件可以傳送 FS_BPIO_OP_STREAM_PAUSE 作業，以暫停數據流上的 BypassIO。 此要求可能來自使用者或核心模式。 所有啟用 BypassIO 的檔案都會停止執行 BypassIO 作業。

具體來說，如果先前允許在數據流上啟用 BypassIO 的篩選，且稍後需要停止 BypassIO（因為外部要求，例如加密檔案或目錄的要求），它可以傳送FS_BPIO_OP_STREAM_PAUSE下篩選堆棧，告訴文件系統停止在指定的數據流上執行 BypassIO。 篩選不應該將此作業傳送至堆疊頂端。

在文件系統傳回之前，它會暫停在數據流上開啟的所有 BypassIO 句柄，並在數據流上完成所有作用中的 BypassIO 作業。 這些動作可確保篩選條件可以在傳回時執行它所需的檔案作業。

這項作業可以多次傳送至相同的數據流。 檔系統會在目前未啟用 BypassIO 的數據流上傳送時予以忽略。

如果篩選條件執行數據流暫停作業，BypassIO 會在磁碟區和記憶體堆疊上繼續。

此作業不應該失敗。

數據流暫停範例：加密篩選

假設加密篩選器允許在未加密的數據流上啟用 BypassIO，但稍後收到加密此數據流的要求。

在加密篩選器繼續之前，它應該呼叫 FsRtlGetBypassIoOpenCount 來判斷 BypassIO 是否在此數據流上為作用中。 如果是，加密篩選會傳送 FS_BPIO_OP_STREAM_PAUSE 作業，要求系統停用 BypassIO。 成功傳回時，會停用並清空 BypassIO，讓篩選條件可以安全地執行加密要求。 若要消除可能的競爭條件，篩選條件必須否決所有未來 FS_BPIO_OP_ENABLE ，並 在此 加密數據流上FS_BPIO_OP_QUERY要求。

FS_BPIO_OP_STREAM_RESUME要求

當導致篩選傳送FS_BPIO_OP_STREAM_PAUSE作業的案例已不存在時，篩選會將FS_BPIO_OP_STREAM_RESUME作業傳送至檔系統，以繼續對指定數據流的 BypassIO 處理。 此要求可能來自使用者或核心模式。

如果在目前未啟用或暫停 BypassIO 時傳送此作業，則會予以忽略。

暫停和繼續不會計算參考計數。 相反地，在繼續時，文件系統會對文件系統堆疊頂端發出 FS_BPIO_OP_QUERY 要求，以判斷是否有任何剩餘的篩選條件仍封鎖。 只有在堆疊中的所有篩選並未封鎖 BypassIO 時，文件系統才會繼續 BypassIO。

此作業不應該失敗。

數據流繼續範例：加密篩選

使用先前所述的FS_BPIO_OP_STREAM_PAUSE案例，表示呼叫 FS_BPIO_OP_STREAM_PAUSE 之後先前加密的檔案已不再加密。 然後篩選條件應該傳送 FS_BPIO_OP_STREAM_RESUME 作業，以允許 BypassIO 在該數據流上繼續。

FS_BPIO_OP_GET_INFO要求

此要求可能來自使用者或核心模式。 文件系統會傳回 FS_BPIO_INFO 結構中磁碟區 BypassIO 的相關信息。