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

Управляющий код FSCTL_SET_SPARSE отмечает обозначенный файл как разреженный. В разреженном  файле, большие области нулей могут не требовать  распределения диска. Пространство для ненулевых данных  должно распределяться по мере того, как оно требуется, когда записывается файл.

Чтобы выполнить эту операцию, вызовите функцию DeviceIoControl со следующими параметрами.

Синтаксис

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // дескриптор файла
  FSCTL_SET_SPARSE,            // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // число возвращаемых байтов
  (LPOVERLAPPED) lpOverlapped  // структура OVERLAPPED
);

Параметры

hDevice

[in] Дескриптор файла или выбранного потока, из которого будет сделан разреженный файл. Чтобы извлечь дескриптор файла, используйте функцию CreateFile. Файл должен открыться или с разрешением записи, или с флажком FILE_FLAG_BACKUP_SEMANTICS. Для получения дополнительной информации, см. Защита файла и права доступа.

Файл должен быть на томе, который является NTFS 5.0 или позже. Эта операция не может вызываться с дескриптором тома или каталога.

dwIoControlCode

[in] Управляющий код для операции.  Для этой операции используйте  FSCTL_SET_SPARSE.

lpInBuffer

Не используется этой операцией; устанавливается в ПУСТО (NULL).

nInBufferSize

Не используется этой операцией; устанавливается в нуль.

lpOutBuffer

Не используется этой операцией; устанавливается в ПУСТО (NULL).

nOutBufferSize

Не используется этой операцией; устанавливается в нуль.

lpBytesReturned

[out] Указатель на переменную, которая получает размер данных, сохраненных в буфере вывода данных, в байтах.

Если параметр lpOverlapped - ПУСТО (NULL), lpBytesReturned не может быть ПУСТО (NULL). Даже тогда, когда операция не возвращает никакого вывода данных, а параметр lpOutBuffer - ПУСТО (NULL), функция DeviceIoControl использует lpBytesReturned. После такой операции, значение параметра lpBytesReturned становится бессмысленным.

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

lpOverlapped

[in] Указатель на структуру OVERLAPPED.

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

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

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

Возвращаемые значения

Если операция завершается успешно, функция DeviceIoControl возвращает не нулевое значение.

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

Замечания

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

Управляющий код FSCTL_SET_SPARSE устанавливает атрибут FILE_ATTRIBUTE_SPARSE_FILE указанному файлу. Единственный способ сбросить бит этого атрибута состоит в том, чтобы переписать файл, например, при помощи вызова функция CreateFile с флажком CREATE_ALWAYS..

Вы не можете создать разреженный  файл при помощи вызова CreateFile с флажком FILE_ATTRIBUTE_SPARSE_FILE в параметре dwFlagsAndAttributes. Вы должны использовать для этого управляющий код FSCTL_SET_SPARSE.

Обратите внимание! на то, что для удаленного (сетевого) файла отметки времени правильно  не могут быть обновлены. Чтобы гарантировать непротиворечивые результаты, используйте не буферизованный ввод - вывод.

Смотри также

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

Размещение и совместимость  FSCTL_SET_SPARSE

К

Windows XP

Да 

л

Windows 2000 Professional

Да

и

Windows NT

Нет

е

Windows Me

Нет

н

Windows 98

Нет

т

Windows 95

Нет

 
С

Windows Server 2003

Да

е Windows 2000 Server Да
р Windows NT Server Нет
в    
е    
р    

Используемая библиотека

-

Используемая DLL -
 Заголовочный файл  

- объявлено в

Winioctl.h

 - включено в

-

 Unicode

Нет

 Замечания по платформе

Не имеется

 

Назад в оглавление
На главную страницу
На оглавление справки

Hosted by uCoz