Поделиться через


Функция NtSetInformationFile (ntifs.h)

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

Синтаксис

__kernel_entry NTSYSCALLAPI NTSTATUS NtSetInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [in]  PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

Параметры

[in] FileHandle

Дескриптор объекта файла. Этот дескриптор создается путем успешного вызова NtCreateFile или NtOpenFile.

[out] IoStatusBlock

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

[in] FileInformation

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

[in] Length

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

[in] FileInformationClass

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

значение FILE_INFORMATION_CLASS Тип возвращаемых сведений
FileBasicInformation (4) Изменение сведений, предоставленных в структуре FILE_BASIC_INFORMATION . Вызывающий объект должен открыть файл с флагом FILE_WRITE_ATTRIBUTES, установленным в параметре DesiredAccess .
FileRenameInformation (10) Измените текущее имя файла, которое предоставляется в FILE_RENAME_INFORMATION структуре. Вызывающий объект должен иметь доступ delete к файлу.
FileDispositionInformation (13) Запрос на удаление файла при его закрытии или отмена ранее запрошенного удаления. Выбор удаления или отмены предоставляется в FILE_DISPOSITION_INFORMATION структуре. Вызывающий объект должен открыть файл с флагом DELETE, установленным в параметре DesiredAccess .
FilePositionInformation (14) Изменение текущих сведений о файле, которые хранятся в FILE_POSITION_INFORMATION структуре.
FileEndOfFileInformation (20) Измените текущие сведения о конце файла, предоставленные в FILE_END_OF_FILE_INFORMATION структуре. Операция может усечь или расширить файл. Вызывающий объект должен открыть файл с флагом FILE_WRITE_DATA, установленным в параметре DesiredAccess .
FileValidDataLengthInformation (39) Измените текущую допустимую длину данных для файла, которая предоставляется в FILE_VALID_DATA_LENGTH_INFORMATION структуре. Файл должен находиться на томе NTFS, а вызывающий объект должен открыть файл с флагом FILE_WRITE_DATA, установленным в параметре DesiredAccess . Неадминистраторы и удаленные пользователи должны иметь привилегию SeManageVolumePrivilege .
FileShortNameInformation (40) Измените текущее короткое имя файла, которое предоставляется в FILE_NAME_INFORMATION структуре. Файл должен находиться на томе NTFS, а вызывающий объект должен открыть файл с флагом DesiredAccess DELETE, установленным в параметре DesiredAccess .
FileIoPriorityHintInformation (43) Измените текущее указание приоритета IRP по умолчанию для дескриптора файла. Новое значение предоставляется в FILE_IO_PRIORITY_HINT_INFORMATION структуре. Эта структура должна быть выровнена по 8 байтам.
FileReplaceCompletionInformation (61) Измените или удалите порт завершения ввода-вывода для указанного дескриптора файла. Вызывающий объект предоставляет указатель на структуру FILE_COMPLETION_INFORMATION , которая указывает дескриптор порта и ключ завершения. Если дескриптор порта не равен NULL, этот дескриптор указывает новый порт завершения ввода-вывода для связи с дескриптором файла. Чтобы удалить порт завершения ввода-вывода, связанный с дескриптором файла, задайте для дескриптора порта в структуре значение NULL. Чтобы получить дескриптор порта, вызывающий объект пользовательского режима может вызвать функцию CreateIoCompletionPort .
FileDispositionInformationEx (64) Запрос на удаление файла или отмену ранее запрошенного удаления. Выбор удаления или отмены, а также параметры времени и способа удаления предоставляются в FILE_DISPOSITION_INFORMATION_EX структуре. Вызывающий объект должен открыть файл с флагом DELETE, установленным в параметре DesiredAccess .
FileCaseSensitiveInformation (71) Изменение сведений, предоставляемых в структуре FILE_CASE_SENSITIVE_INFORMATION . Вызывающий объект должен открыть файл с флагом FILE_WRITE_ATTRIBUTES, установленным в параметре DesiredAccess . Это значение доступно начиная с Windows 10 версии 1803.
FileLinkInformation (72) Создайте жесткую ссылку на существующий файл, который указан в FILE_LINK_INFORMATION структуре. Не все файловые системы поддерживают жесткие ссылки; Например, NTFS делает , а FAT — нет.
FileCaseSensitiveInformationForceAccessCheck (75) Изменение сведений, предоставляемых в структуре FILE_CASE_SENSITIVE_INFORMATION . Вызывающий объект должен открыть файл с флагом FILE_WRITE_ATTRIBUTES, установленным в параметре DesiredAccess . Это специальная версия операции FileCaseSensitiveInformation, которая используется для принудительного выполнения IOManager проверок доступа для драйвера режима ядра, аналогично проверкам, которые применяются к вызывающей объекту пользовательского режима. Эта операция распознается только IOManager, и файловая система никогда не должна получать ее. Это значение доступно начиная с Windows 10 версии 1803.
FileKnownFolderInformation (76) Структура FILE_KNOWN_FOLDER_INFORMATION . Доступно начиная с Windows Server 2022.

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

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

Комментарии

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

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

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

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

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

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

Примечание

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

Для вызовов из драйверов режима ядра версии NtXxx и ZwXxx подпрограммы собственных системных служб Windows могут вести себя по-разному, так как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между версиями процедуры NtXxx**** и ZwXxx**** см. в разделе Использование версий Nt и Zw собственных процедур системных служб.

Требования

Требование Значение
Минимальная версия клиента Windows 2000.
Целевая платформа Универсальное
Верхняя часть ntifs.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL (см. раздел "Примечания")
Правила соответствия DDI HwStorPortProhibitedDIs, PowerIrpDDis

См. также раздел

CreateIoCompletionPort

FILE_BASIC_INFORMATION

FILE_COMPLETION_INFORMATION

FILE_DISPOSITION_INFORMATION

FILE_END_OF_FILE_INFORMATION

FILE_IO_PRIORITY_HINT_INFORMATION

FILE_LINK_INFORMATION

FILE_NAME_INFORMATION

FILE_POSITION_INFORMATION

FILE_RENAME_INFORMATION

FILE_VALID_DATA_LENGTH_INFORMATION

ZwClose

ZwCreateFile

ZwOpenFile

ZwQueryInformationFile