FSCTL_FILE_LEVEL_TRIM控件程式代碼

發行項
05/30/2024

FSCTL_FILE_LEVEL_TRIM控件程式代碼提供方法，以修剪檔案中的數據範圍。檔案修剪範圍會轉譯為基礎儲存裝置，以將其資源組織優化，以改善存取效能。 FSCTL_FILE_LEVEL_TRIM要求可讓虛擬磁碟檔案維持固定大小配置，同時修剪實體記憶體以對應至虛擬磁碟上釋放的數據範圍。

若要執行這項作業，請使用下列參數呼叫 FltFsControlFile 或 ZwFsControlFile。

參數

實例 [in]： 僅限 FltFsControlFile 。呼叫端的不透明實例指標。這個參數是必要的，而且不能是 NULL。
FileObject [in]： 僅 FltFsControlFile 。要修剪數據的檔案檔案物件指標。這個參數是必要的，而且不能是 NULL。
FileHandle [in]： 僅限 ZwFsControlFile 。要修剪數據的檔案句柄。這個參數是必要的，而且不能是 NULL。
FsControlCode [in]：控制作業的程序代碼。針對此作業使用 FSCTL_FILE_LEVEL_TRIM 。
InputBuffer [in]：FILE_LEVEL_TRIM結構的指標，其中包含檔案的修剪範圍陣列。
InputBufferLength [in]： InputBuffer 參數指向之緩衝區的大小，以位元組為單位。此值至少必須是sizeof（FILE_LEVEL_TRIM）。
OutputBuffer [out]：選擇性 FILE_LEVEL_TRIM_OUTPUT 結構的指標，可接收修剪作業的結果。
OutputBufferLength [out]：OutputBuffer 參數所指向之緩衝區的大小，以位元組為單位。如果 outputBuffer 中包含FILE_LEVEL_TRIM_OUTPUT，此值至少必須是 sizeof（FILE_LEVEL_TRIM_OUTPUT）。否則，這會設定為 0。

狀態區塊

FltFsControlFile 或 ZwFsControlFile 會傳回STATUS_SUCCESS或可能是下列其中一個值。

代碼	意義
STATUS_INVALID_PARAMETER	要修剪的檔案會經過壓縮或加密、輸入或輸出緩衝區長度無效，或未指定任何修剪範圍。
STATUS_INSUFFICIENT_RESOURCES	內部資源配置失敗。
STATUS_FILE_LOCK_CONFLICT	修剪範圍是先前鎖定位元組範圍的一部分。
STATUS_VOLUME_DISMOUNTED	檔案所在的磁碟區未掛接。
STATUS_PURGE_FAILED	修剪範圍的快取清除失敗。
STATUS_NO_RANGES_PROCESSED	修剪範圍陣列中未處理任何範圍。

備註

在特定存儲設備上執行修剪可以大幅改善其未來的寫入效能。 Trim 也會將資源傳回精簡布建的記憶體系統中的配置集區。當虛擬磁碟上刪除檔案時，虛擬磁碟檔案本身的大小不會變更。虛擬磁碟上釋放的數據範圍不會在虛擬磁碟檔案所在的實體記憶體上修剪。虛擬磁碟裝置可以通知檔系統，虛擬磁碟檔案中的特定數據範圍可以在具有FSCTL_FILE_LEVEL_TRIM要求的實體存儲設備上修剪。檔系統接著會對實體記憶體發出修剪要求。 管理資料庫或記憶體交換檔案的服務應用程式也可以發出FSCTL_FILE_LEVEL_TRIM要求。

FSCTL_FILE_LEVEL_TRIM控件程式代碼會嘗試從儲存裝置修剪檔案選取的位元組範圍。位元組範圍包含在 FILE_LEVEL_TRIM 結構的 Ranges 陣列中。 Ranges 陣列中包含一或多個FILE_LEVEL_TRIM_RANGE結構。

在範圍陣列中包含重疊的範圍不一定是錯誤狀況。這取決於基礎記憶體處理範圍處理的方式。

修剪的範圍會清除為檔案系統快取中的頁面。為了符合快取頁面大小，修剪範圍的長度會向下調整為PAGE_SIZE的倍數。此外，如果修剪範圍位移未從頁面界限開始，則會對齊下一個頁面界限。使用這些條件約束時，修剪範圍長度會在其位移未對齊頁面或長度不是頁面大小倍數時減少。如果原始長度小於兩頁，且位移未對齊頁面，修剪範圍長度可能會減少為 0。

如果指定修剪範圍或超過檔尾（EOF）的頁面調整，則會忽略範圍。不過，在 EOF 之前對齊範圍位移，但經過 EOF 的長度會調整為頁面大小倍 <數 = EOF。

壓縮或加密的檔案不支援檔案層級修剪（已 設定ATTRIBUTE_FLAG_COMPRESSION_MASK 或 ATTRIBUTE_FLAG_ENCRYPTED屬性的 檔案）。

檔案修剪會在任何交易之外執行。修剪作業無法回復。

使用疏鬆檔案（已 設定ATTRIBUTE_FLAG_SPARSE 屬性的檔案），則會忽略檔案中未配置部分的修剪範圍。

當包含在 OutputBuffer 中時，FILE_LEVEL_TRIM_OUTPUT的 NumRangesProcessed 成員會指出已成功處理的修剪範圍數目。 如果在處理修剪範圍期間發生錯誤，NumRangesProcessed 會指定其餘未處理範圍的起始索引，結尾為 FILE_LEVEL_TRIM - 1 的 NumRanges 成員。