Управляющий код FSCTL_QUERY_ALLOCATED_RANGES

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

Возвращенные области - всегда, по крайней мере, в пределах области, определенной в буфере lpInBuffer.

Если буфер вывода данных является слишком маленьким для любых данных, то вызов завершается ошибкой, GetLastError возвращает код ошибки ERROR_INSUFFICIENT_BUFFER, а итоговое число возвращаемых байт равняется нулю.

Если параметр lpOverlapped - не ПУСТО (NULL), то - lpBytesReturned может быть ПУСТО (NULL). Если этот параметр - не ПУСТО (NULL) и операция возвращает данные, lpBytesReturned не имеет смысла до тех пор, пока не завершиться асинхронная операция. Чтобы получить данные о числе возвращаемых данных, вызовите функцию GetOverlappedResult. Если  параметр hDevice связан с портом завершения ввода-вывода данных (I/O), Вы можете извлечь число возвращаемых данных при помощи вызова функции GetQueuedCompletionStatus.

Если параметр hDevice открывался без установки флажка FILE_FLAG_OVERLAPPED, параметр lpOverlapped игнорируется.

Если параметр hDevice открывался с флажком FILE_FLAG_OVERLAPPED, операция выполняется как перекрывающая (асинхронная) операция. В этом случае, параметр lpOverlapped должен указать на допустимую структуру OVERLAPPED, которая содержит дескриптор объекта события. Иначе, функция завершается ошибкой непредсказуемыми способами.

Для асинхронных операций, функция DeviceIoControl возвращает значение немедленно, а объект события подает сигнал, когда операция завершается. В противном случае, функция не возвращает значение до тех пор, пока операция не завершится или не произойдет ошибка.

Если операция завершается успешно, функция DeviceIoControl возвращает не нулевое значение, а буфер вывода данных, на который указывает параметр lpOutBuffer содержит массив допустимых структур FILE_ALLOCATED_RANGE_BUFFER.

Если операция завершается ошибкой, DeviceIoControl возвращает  нуль. Содержание буфера вывода данных, на который указывает lpOutBuffer не имеет смысла. Чтобы получить дополнительную информацию об ошибке, вызовите GetLastError.

Как включить асинхронный ввод-вывод в эту операцию, см. раздел Замечаний в описании функции DeviceIoControl.

NTFS округляет введенное смещение файла вниз , а длину вверх до подходящей границы, и затем начинает обход всего файла.

Операционная система не отслеживает каждый кусочек нулевых или ненулевых данных. Поскольку нуль - часто совершенно допустимая данная величина, он будет вводить в заблуждение. Вместо этого, система отслеживает области, куда распределяется дисковое пространство. Куда дисковое пространство не распределяется, все принятые данные будут нулевыми. Назначенное хранилище данных может содержать нулевые или ненулевые данные. Так что вся эта операция возвращает информацию о частях файла, где могут быть расположены ненулевые данные. Эти данные передаются прикладной программе, чтобы просматривать эти части файла в соответствии с соглашениями о представлении данных в приложении.

Каждая запись в массиве вывода данных содержит смещение и длину,  указывающие область в файле, которая может содержать ненулевые данные. Фактические отличные от нуля данные, если таковые вообще имеются, находятся где-нибудь, внутри этой области и вызывающая программа должны искать далее внутри области, чтобы определить местонахождение их и выяснить, является ли они действительно допустимыми данными. Внутри области могут существовать несколько экземпляров допустимых данных.

Распределенные области подчиняются правилу, по которому удаленный (сетевой) отображаемый в памяти файл и открытый дескриптор файла не обязательно связаны. Если Вы отобразили в памяти разреженный сетевой файл и записали ненулевые данные в предварительно не распределенных областях файла, дисковое пространство будет распределено под новые данные. К тому же, вызов FSCTL_QUERY_ALLOCATED_RANGES после этого не обязательно возвратит  правильный список распределенных областей. Чтобы гарантировать связь между видимой памятью и дескриптором файла, сбросьте данные в файл при помощи функции FlushViewOfFile.

Разреженные файлы, Управляющие коды, используемые в управлении файлами, DeviceIoControl,  FILE_ALLOCATED_RANGE_BUFFER, FSCTL_SET_SPARSE, FSCTL_SET_ZERO_DATA