FSCTL_QUERY_ALLOCATED_RANGES IOCTL (ntifs.h)

Статья
11/14/2023

FSCTL_QUERY_ALLOCATED_RANGES запрашивает сканирование файла или альтернативного потока для поиска диапазонов байтов, которые могут содержать ненулевые данные, а затем возвращает сведения об этих диапазонах. Только разреженные файлы могут иметь нулевые диапазоны, известные операционной системе. Для других файлов выходной буфер будет содержать только один диапазон, содержащий начальную точку и запрошенную длину.

Основной код

FSCTL_QUERY_ALLOCATED_RANGES

Входной буфер

Указатель на структуру FILE_ALLOCATED_RANGE_BUFFER , указывающую диапазон для запроса выделения.

Длина входного буфера

Размер структуры FILE_ALLOCATED_RANGE_BUFFER , на которую указывает InputBuffer , в байтах.

Выходной буфер

Указатель на массив с нулевым или более FILE_ALLOCATED_RANGE_BUFFER элементами данных, в которых возвращаются результаты запроса. Дополнительную информацию см. ниже.

Длина выходного буфера

Размер буфера, на который указывает OutputBuffer , в байтах.

Буфер входных и выходных данных

Недоступно

Длина входного/выходного буфера

Недоступно

Блок состояния

Зарезервировано для системного использования.

Параметр	Описание
Экземпляр	[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 возвращает массив из нуля или более FILE_ALLOCATED_RANGE_BUFFER элементов данных в буфере, на который указывает OutputBuffer . Количество возвращаемых элементов 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