Функция ZwSetInformationFile (wdm.h)

Статья
11/07/2024

Программа ZwSetInformationFile изменяет различные виды сведений об объекте файла.

Синтаксис

NTSYSAPI NTSTATUS ZwSetInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [in]  PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

Параметры

[in] FileHandle

Дескриптор объекта файла. Этот дескриптор создается с помощью успешного вызова ZwCreateFile или ZwOpenFile.

[out] IoStatusBlock

Указатель на структуру IO_STATUS_BLOCK, которая получает окончательное состояние завершения и сведения о запрошенной операции. Элемент Information получает количество байтов, заданных в файле.

[in] FileInformation

Указатель на буфер, содержащий сведения, заданные для файла. Конкретная структура в этом буфере определяется параметром FileInformationClass. Например, если параметр FileInformationClassзадан в константе FileDispositionInformationEx, этот параметр должен быть указателем на структуру FILE_DISPOSITION_INFORMATION_EX.

[in] Length

Размер буфера FileInformation в байтах.

[in] FileInformationClass

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

значение FileInformationClass	Значение
FileBasicInformation	Измените сведения, предоставленные в структуре FILE_BASIC_INFORMATION. Вызывающий объект должен открыть файл с флагом FILE_WRITE_ATTRIBUTES в параметре DesiredAccess.
FileDispositionInformation	Запрос на удаление файла при закрытии или отмене ранее запрошенного удаления. Выбор того, следует ли удалять или отменять, предоставляется в FILE_DISPOSITION_INFORMATION структуре. Вызывающий объект должен открыть файл с флагом DELETE, заданным в параметре DesiredAccess.
FileDispositionInformationEx	Запрос на удаление файла или отмену ранее запрошенного удаления. Выбор того, следует ли удалять или отменять, а также параметры того, когда и как следует выполнять удаление, предоставляются в структуре FILE_DISPOSITION_INFORMATION_EX. Вызывающий объект должен открыть файл с флагом DELETE** в параметре DesiredAccess.
FileEndOfFileInformation	Измените текущие сведения о конце файла, предоставленные в FILE_END_OF_FILE_INFORMATION структуре. Операция может усечь или расширить файл. Вызывающий объект должен открыть файл с флагом FILE_WRITE_DATA в параметре DesiredAccess.
FileIoPriorityHintInformation	Измените текущее указание приоритета IRP по умолчанию для дескриптора файла. Новое значение предоставляется в FILE_IO_PRIORITY_HINT_INFORMATION структуре. Эта структура должна быть выровнена по 8 байтам.
FileLinkInformation	Создайте жесткую ссылку на существующий файл, который указан в структуре FILE_LINK_INFORMATION. Не все файловые системы поддерживают жесткие ссылки; Например, NTFS делает, пока FAT не выполняется.
FilePositionInformation	Измените текущие сведения о файле, которые хранятся в FILE_POSITION_INFORMATION структуре.
FileRenameInformation	Измените текущее имя файла, которое предоставляется в структуре FILE_RENAME_INFORMATION. Вызывающий объект должен иметь доступ DELETE к файлу.
FileShortNameInformation	Измените текущее короткое имя файла, которое предоставляется в FILE_NAME_INFORMATION структуре. Файл должен находиться в томе NTFS, и вызывающий объект должен открыть файл с флагом DesiredAccess DELETE в параметре DesiredAccess.
FileIoCompletionNotificationInformation	Измените флаги уведомлений о завершении ввода-вывода файла. Поддерживает те же флаги, что и SetFileCompletionNotificationModes.
FileValidDataLengthInformation	Измените текущую допустимую длину данных для файла, который предоставляется в FILE_VALID_DATA_LENGTH_INFORMATION структуре. Файл должен находиться в томе NTFS, и вызывающий объект должен открыть файл с флагом FILE_WRITE_DATA, установленным в параметре DesiredAccess. Неадминистраторы и удаленные пользователи должны иметь права SeManageVolumeeGe.
FileReplaceCompletionInformation	Измените или удалите порт завершения ввода-вывода для указанного дескриптора файлов. Вызывающий объект предоставляет указатель на структуру FILE_COMPLETION_INFORMATION, указывающую дескриптор порта и ключ завершения. Если дескриптор порта не имеет значения NULL, этот дескриптор указывает новый порт завершения ввода-вывода для связывания с дескриптором файла. Чтобы удалить порт завершения ввода-вывода, связанный с дескриптором файла, задайте для дескриптора порта в структуре значение NULL. Чтобы получить дескриптор порта, вызывающий пользователь может вызвать функцию CreateIoCompletionPort.

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

ZwSetInformationFile возвращает STATUS_SUCCESS или соответствующее состояние ошибки.

Замечания

ZwSetInformationFile изменяет сведения о файле. Он игнорирует любой элемент структуры FILE_XXX_INFORMATION, которая не поддерживается определенным устройством или файловой системой.

Если fileInformationClass FileDispositionInformation, можно передать FileHandle в ZwClose, но не ZwXxxподпрограммой File. Так как FileDispositionInformation приводит к тому, что файл будет помечен для удаления, это ошибка программирования для попытки любой последующей операции на дескрипторе, отличном от закрытия.

Если FileInformationClassFilePositionInformation, а предыдущий вызов ZwCreateFile включен флаг FILE_NO_INTERMEDIATE_BUFFERING в параметре CreateOptions, применяются определенные ограничения для элемента CurrentByteOffset структуры FILE_POSITION_INFORMATION. Дополнительные сведения см. в ZwCreateFile.

Если FileInformationClass значение FileEndOfFileInformation, а элемент EndOfFile FILE_END_OF_FILE_INFORMATION указывает смещение за пределами текущей метки конца файла, ZwSetInformationFile расширяет файл и заполняет расширение нулями.

Дополнительные сведения о работе с файлами см. в использовании файлов в драйвере.

Вызывающие ZwSetInformationFile должны выполняться в IRQL = PASSIVE_LEVEL и со специальными API ядра, включенными.

Если вызов этой функции происходит в пользовательском режиме, следует использовать имя "NtSetInformationFile" вместо "ZwSetInformationFile".

Для вызовов драйверов в режиме ядра NtXxx и ZwXxx версии подпрограммы Windows Native System Services могут вести себя по-разному в том, как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между NtXxx и ZwXxx версиями подпрограммы см. в разделе Using Nt and Zw Versions of the Native System Services Routines.

Требования

Требование	Ценность
целевая платформа	Всеобщий
заголовка	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")
правил соответствия DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)