FSCTL_QUERY_ALLOCATED_RANGES IOCTL (ntifs.h)

项目
11/14/2023

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 元素数的计算方法是将 LengthReturned 中返回的值除以 sizeof(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 加长度大于 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

通过