Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Подпрограмма 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, и файловая система никогда не должна получать ее. Это значение доступно начиная с Windows 10 версии 1803. |
| FileKnownFolderInformation (76) | Структура FILE_KNOWN_FOLDER_INFORMATION . Доступно начиная с Windows Server 2022. |
Возвращаемое значение
NtSetInformationFile возвращает STATUS_SUCCESS или соответствующее состояние ошибки.
Замечания
NtSetInformationFile изменяет сведения о файле. Он игнорирует любой член структуры FILE_XXX_INFORMATION , которая не поддерживается определенным устройством или файловой системой.
Если для FileInformationClass задано значение FileDispositionInformation, вы можете впоследствии передать FileHandleв NtClose, но не в другую подпрограмму ZwXxxFile. Так как FileDispositionInformation приводит к тому, что файл будет помечен для удаления, это ошибка программирования для попытки любой последующей операции на дескрипторе, отличном от закрытия.
Если в параметре CreateOptions задано значение FileInformationClass, а предыдущий вызов NtCreateFile включал флаг FILE_NO_INTERMEDIATE_BUFFERING в параметр CreateOptions, применяются определенные ограничения для элемента CurrentByteOffset структуры FILE_POSITION_INFORMATION. Дополнительные сведения см. в разделе NtCreateFile.
Если для FileInformationClass задано значение FileEndOfFileInformation, а член EndOfFileFILE_END_OF_FILE_INFORMATION указывает смещение, превышающее текущую метку конца файла, NtSetInformationFile расширяет файл и заполняет расширение нулями.
Дополнительные сведения о работе с файлами см. в разделе "Использование файлов в драйвере".
Вызовы NtSetInformationFile должны выполняться в 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.
Требования
| Требование | Ценность |
|---|---|
| Минимальный поддерживаемый клиент | Windows 2000. |
| целевая платформа | Всеобщий |
| Header | ntifs.h (включая Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (см. раздел "Примечания") |
| правил соответствия DDI |
HwStorPortProhibitedDDIs, PowerIrpDDis |
См. также
FILE_IO_PRIORITY_HINT_INFORMATION