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 元素数的计算方法是将 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 |