FSCTL_QUERY_ALLOCATED_RANGES IOCTL （ntifs.h）
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。
| 參數 | 描述 |
|---|---|
| 實例 | [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 元素數目會以 sizeof(FILE_ALLOCATED_RANGE_BUFFER)除以 LengthReturned 中所傳回的值來計算。 傳回的範圍必須與 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 |