FSCTL_QUERY_ALLOCATED_RANGES IOCTL (ntifs.h)

發行項
02/26/2024

FSCTL_QUERY_ALLOCATED_RANGES 要求掃描檔案或替代數據流，尋找可包含非零數據的位元組範圍，然後傳回這些範圍的資訊。只有疏鬆檔案可以有操作系統已知的零範圍。對於其他檔案，輸出緩衝區只會包含包含起始點和所要求長度的單一範圍。

主要程序代碼

FSCTL_QUERY_ALLOCATED_RANGES

輸入緩衝區

FILE_ALLOCATED_RANGE_BUFFER 結構的指標，指出要查詢配置的範圍。

輸入緩衝區長度

InputBuffer 指向的FILE_ALLOCATED_RANGE_BUFFER結構大小，以位元組為單位。

輸出緩衝區

傳回查詢結果之零個或多個 FILE_ALLOCATED_RANGE_BUFFER 數據元素陣列的指標。如需詳細資訊，請參閱下方內容。

輸出緩衝區長度

OutputBuffer 指向的緩衝區大小，以位元組為單位。

輸入/輸出緩衝區

n/a

輸入/輸出緩衝區長度

n/a

狀態區塊

保留供系統使用。

備註

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

參數	Description
執行個體	[in]僅適用於 FltFsControlFile 。呼叫端的不透明實例指標。這個參數是必要的，而且不能是 NULL。
FileObject	[in]僅適用於 FltFsControlFile 。此要求目標之檔案或目錄的檔案物件指標。這個參數是必要的，而且不能是 NULL。
FileHandle	[in]僅適用於 ZwFsControlFile 。此要求目標之檔案或目錄的檔案句柄。這個參數是必要的，而且不能是 NULL。
IoStatusBlock	[out]僅適用於 ZwFsControlFile 。包含要求最終狀態之IO_STATUS_BLOCK 結構的指標。
FsControlCode	[in]設定為 FSCTL_QUERY_ALLOCATED_RANGES。
InputBuffer	[in] FILE_ALLOCATED_RANGE_BUFFER 結構的指標，指出要查詢配置的範圍。
InputBufferLength	[in] InputBuffer 指向的緩衝區大小，以位元組為單位。
OutputBuffer	[out]傳回查詢結果之零個或多個 FILE_ALLOCATED_RANGE_BUFFER 數據元素陣列的指標。如需詳細資訊，請參閱下方內容。
OutputBufferLength	[out] OutputBuffer 指向的緩衝區大小，以位元組為單位。
LengthReturned	[out]呼叫端配置的變數指標，該變數會接收在 OutputBuffer 緩衝區中傳回之資訊的位元元組大小。

FSCTL_QUERY_ALLOCATED_RANGES傳回 OutputBuffer 指向之緩衝區中零個或多個FILE_ALLOCATED_RANGE_BUFFER數據元素的陣列。傳回 的FILE_ALLOCATED_RANGE_BUFFER 元素數目會除以的 LengthReturnedsizeof(FILE_ALLOCATED_RANGE_BUFFER)中所傳回的值來計算。傳回的範圍必須與 InputBuffer 中指定的範圍交集。檔案沒有配置的範圍時，會傳回零 FILE_ALLOCATED_RANGE_BUFFER 數據元素。

傳回值

FSCTL_QUERY_ALLOCATED_RANGES 在成功完成時傳回STATUS_SUCCESS;否則會傳回錯誤碼。常見的錯誤碼如下。

錯誤碼	意義
STATUS_INVALID_PARAMETER	有一個參數無效。例如：句柄不是檔案; InputBuffer 的大小小於 FILE_ALLOCATED_RANGE_BUFFER 結構的大小; FileOffset 小於零; 長度小於零;或 FileOffset 加上 Length 大於 0x7FFFFFFFFFFFFFFF。
STATUS_INVALID_USER_BUFFER	輸入緩衝區或輸出緩衝區未對齊 4 位元組界限。
STATUS_BUFFER_TOO_SMALL	輸出緩衝區太小而無法包含 FILE_ALLOCATED_RANGE_BUFFER 結構。
STATUS_BUFFER_OVERFLOW	輸出緩衝區太小，無法包含所需的 FILE_ALLOCATED_RANGE_BUFFER 結構數目。

規格需求

需求	值
最低支援的用戶端	Windows 2000
標頭	ntifs.h

另請參閱

FILE_ALLOCATED_RANGE_BUFFER

FltFsControlFile

ZwFsControlFile