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

структура FILE_RENAME_INFORMATION (ntifs.h)

  • Статья

Структура FILE_RENAME_INFORMATION используется для переименования файла.

Синтаксис

typedef struct _FILE_RENAME_INFORMATION {
#if (_WIN32_WINNT >= _WIN32_WINNT_WIN10_RS1)
    union {
        BOOLEAN ReplaceIfExists;  // FileRenameInformation
        ULONG Flags;              // FileRenameInformationEx
    } DUMMYUNIONNAME;
#else
    BOOLEAN ReplaceIfExists;
#endif
    HANDLE RootDirectory;
    ULONG FileNameLength;
    WCHAR FileName[1];
} FILE_RENAME_INFORMATION, *PFILE_RENAME_INFORMATION;

Члены

DUMMYUNIONNAME

DUMMYUNIONNAME.ReplaceIfExists

Задайте значение TRUE, чтобы указать, что если файл с заданным именем уже существует, он должен быть заменен заданным файлом. Установите значение FALSE, если операция переименования должна завершиться ошибкой, если файл с заданным именем уже существует.

DUMMYUNIONNAME.Flags

Флаги для операции переименования. Это поле применимо только при использовании с классом сведений FileRenameInformationEx.

Ниже приведены возможные значения:

Ценность Значение
FILE_RENAME_REPLACE_IF_EXISTS (0x00000001) Если файл с заданным именем уже существует, его следует заменить указанным файлом. Эквивалентен полю ReplaceIfExists, используемому с классом сведений FileRenameInformation.
FILE_RENAME_POSIX_SEMANTICS (0x00000002) Если FILE_RENAME_REPLACE_IF_EXISTS также задано, разрешите замену файла, даже если в нем есть дескриптор. Существующие дескрипторы для замененного файла продолжают быть допустимыми для таких операций, как чтение и запись. Любое последующее открытие целевого имени откроет переименованный файл, а не замененный файл.
FILE_RENAME_SUPPRESS_PIN_STATE_INHERITANCE (0x00000004) При переименовании файла в новый каталог отключите все правила наследования, связанные с FILE_ATTRIBUTE_PINNED и FILE_ATTRIBUTE_UNPINNED атрибутами файла.
FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE (0x00000008) При переименовании файла в новый каталог отключите все правила наследования, связанные со свойством идентификатора резервирования хранилища файла.
FILE_RENAME_NO_INCREASE_AVAILABLE_SPACE (0x00000010) Если FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE не указан, при переименовании файла в новый каталог автоматически измените размер затронутых областей резервирования хранилища, чтобы предотвратить увеличение свободного места пользователя на томе. Требуется управление доступом к томам.
FILE_RENAME_NO_DECREASE_AVAILABLE_SPACE (0x00000020) Если FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE не указан, при переименовании файла в новый каталог автоматически измените размер затронутых областей резервирования хранилища, чтобы предотвратить уменьшение свободного места на томе. Требуется управление доступом к томам.
FILE_RENAME_PRESERVE_AVAILABLE_SPACE (0x00000030) Эквивалентно указанию FILE_RENAME_NO_INCREASE_AVAILABLE_SPACE и FILE_RENAME_NO_DECREASE_AVAILABLE_SPACE.
FILE_RENAME_IGNORE_READONLY_ATTRIBUTE (0x00000040) Если FILE_RENAME_REPLACE_IF_EXISTS также указан, можно заменить файл, даже если он доступен только для чтения. Требуется WRITE_ATTRIBUTES доступ к заменяемом файлу.
FILE_RENAME_FORCE_RESIZE_TARGET_SR (0x00000080) Если FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE не указан, при переименовании файла в новый каталог, который является частью другой области резервирования хранилища, всегда увеличивает резервную область хранилища целевого каталога на полный размер переименованного файла. Требуется управление доступом к томам.
FILE_RENAME_FORCE_RESIZE_SOURCE_SR (0x00000100) Если FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE не указано, при переименовании файла в новый каталог, который является частью другой области резервирования хранилища, всегда сжимайте резервную область хранилища исходного каталога до полного размера переименованного файла. Требуется управление доступом к томам.
FILE_RENAME_FORCE_RESIZE_SR (0x00000180) Эквивалентен указанию FILE_RENAME_FORCE_RESIZE_TARGET_SR и FILE_RENAME_FORCE_RESIZE_SOURCE_SR.

ReplaceIfExists

Задайте значение TRUE, чтобы указать, что если файл с заданным именем уже существует, он должен быть заменен заданным файлом. Установите значение FALSE, если операция переименования должна завершиться ошибкой, если файл с заданным именем уже существует.

RootDirectory

Дескриптор, который IopOpenLinkOrRenameTarget используется для открытия целевого каталога.

Если файл не перемещается в другой каталог или если элемент FileName содержит полное имя пути, этот элемент имеет значение NULL. В противном случае это дескриптор корневого каталога, в котором файл будет находиться после переименования.

Чтобы выполнить две открытые операции, которые не вызывают конфликт общего доступа, можно открыть RootDirectory, запрашивая обход | read-attribute. IopOpenLinkOrRenameTarget может выполнить относительное открытие, запрашивая FILE_WRITE_DATA | СИНХРОНИЗИРОВАТЬ. Эти два открытия не вызывают конфликта совместного доступа.

FileNameLength

Длина в байтах нового имени файла.

FileName[1]

Первый символ строки с расширенным символом, содержащей новое имя файла. За этим следует в памяти оставшаяся часть строки. Если элемент RootDirectory имеет значение NULL, а файл перемещается в другой каталог, этот элемент указывает полное имя пути, которое будет назначено файлу. В противном случае указывает только имя файла или относительное имя пути.

Замечания

Структура FILE_RENAME_INFORMATION используется для переименования файла. Эта операция может выполняться в любом из следующих способов:

  • Вызовите FltSetInformationFile или ZwSetInformationFile, передав FileRenameInformation в качестве значения FileInformationClass и передавая выделенный вызывающим буфер в виде структуры FILE_RENAME_INFORMATION для значения FileInformation. Параметр FileHandle указывает файл, который нужно переименовать.

  • Создайте IRP с основным кодом функции IRP_MJ_SET_INFORMATION.

Мини-фильтры файловой системы должны использовать FltSetInformationFile, а не ZwSetInformationFile, чтобы переименовать файл.

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

Строка имени файла в элементе FileName должна быть указана в одной из следующих форм.

  • Простое имя файла. (Элемент rootDirectory имеет значение NULL.) В этом случае файл просто переименовывается в одном каталоге. То есть операция переименования изменяет имя файла, но не его расположение.

  • Полное имя файла. (Элемент rootDirectory имеет значение NULL.) В этом случае операция переименования изменяет имя и расположение файла.

  • Относительное имя файла. В этом случае элемент RootDirectory содержит дескриптор целевого каталога для операции переименования. Имя файла должно быть простым именем файла.

Общие правила для операций переименования:

  • Файл или каталог можно переименовать только в томе. Другими словами, операция переименования не может привести к перемещению файла или каталога в другой том.

  • Корневой каталог тома нельзя переименовать.

  • Если ReplaceIfExists имеет значение FALSE, а целевой объект существует, операция переименования завершится ошибкой.

  • Даже если ReplaceIfExists имеет значение TRUE, операция переименования по-прежнему завершится ошибкой, если файл с тем же именем уже существует и является каталогом, файлом только для чтения или текущим исполняемым файлом.

  • Файлы и каталоги тома нельзя переименовать, если том является томом только для чтения, например томом CDFS или томом NTFS только для чтения.

Специальные правила для переименования открытых файлов:

  • Невозможно переименовать файл, если он имеет открытые дескрипторы, если только он не открыт из-за пакетной оппортунистической блокировки (oplock) и пакетной блокировки можно немедленно разбить.

  • Файл нельзя переименовать, если файл с тем же именем существует и имеет открытые дескрипторы (за исключением случая пакетной операции, описанного ранее).

  • Каталог нельзя переименовать, если он или какой-либо из его подкаталогов содержит файл с открытыми дескрипторами (за исключением случая пакетной операции, описанного ранее).

Специальные правила переименования потоков данных NTFS:

  • Не удается переименовать поток каталогов по умолчанию.

  • Новое имя потока должно начинаться с двоеточия (:).

  • Поток данных можно переименовать только в том же файле. Другими словами, операция переименования не может привести к перемещению потока данных в другой файл.

  • Поток данных в каталоге нельзя переименовать в поток данных по умолчанию.

  • Если ReplaceIfExists имеет значение TRUE, операция переименования будет выполнена только в том случае, если поток с тем же именем не существует или является потоком данных нулевой длины.

  • "Переименование" потока данных по умолчанию допускается, но это не является истинным переименованием, так как он оставляет за потоком данных по умолчанию нулевой длины.

Размер буфера fileInformation, переданного ZwSetInformationFile или FltSetInformationFile, должен быть >= размер(FILE_RENAME_INFORMATION) плюс размер в байтах строки FileName.

Требования

Требование Ценность
заголовка ntifs.h (include Ntifs.h, Fltkernel.h)

См. также

FltSetInformationFile

IRP_MJ_SET_INFORMATION

ZwSetInformationFile