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) 如果已存在具有给定名称的文件，则应将其替换为给定的文件。 等效于与 FileRenameInformation 信息类一起使用的 ReplaceIfExists 字段。
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) 将文件重命名为新目录时，禁止显示与文件的存储保留 ID 属性相关的任何继承规则。
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 的值传递，并为 FileInformation 的值传递格式化为FILE_RENAME_INFORMATION结构的调用方分配的缓冲区。 FileHandle 参数指定要重命名的文件。

  • 创建包含主函数代码 IRP_MJ_SET_INFORMATION的 IRP。

文件系统微筛选器必须使用 FltSetInformationFile（而不是 ZwSetInformationFile）重命名文件。

重命名文件需要对文件具有 DELETE 访问权限，以便可以从当前父目录中删除目录条目，以及具有在新的父目录文件中创建新条目的适当访问权限。

FileName 成员中的文件名字符串必须在以下格式之一中指定。

  • 一个简单的文件名。 (RootDirectory 成员为 NULL.) 在本例中，只需在同一目录中重命名文件。 也就是说，重命名操作会更改文件的名称，但不会更改其位置。

  • 完全限定的文件名。 (RootDirectory 成员为 NULL.) 在这种情况下，重命名操作会更改文件的名称和位置。

  • 相对文件名。 在这种情况下， RootDirectory 成员包含重命名操作的目标目录的句柄。 文件名本身必须是一个简单的文件名。

重命名操作的一般规则：

  • 只能在卷中重命名文件或目录。 换句话说，重命名操作不能导致文件或目录移动到其他卷。

  • 无法重命名卷的根目录。

  • 如果 ReplaceIfExists 设置为 FALSE，并且目标存在，则重命名操作将失败。

  • 即使 ReplaceIfExists 设置为 TRUE，如果同名的文件已存在并且是目录、只读文件或当前正在执行的文件，则重命名操作仍会失败。

  • 如果卷是只读卷（例如 CDFS 卷或只读 NTFS 卷），则无法重命名卷的文件和目录。

重命名打开文件的特殊规则：

  • 如果文件有任何打开的句柄，则无法重命名该文件，除非它只是因为批处理机会锁 (oplock) 而打开，并且批处理 oplock 可以立即中断。

  • 如果存在同名的文件并且 (打开句柄，则无法重命名文件，但前面) 所述的批处理锁定情况除外。

  • 如果目录或其任何子目录包含具有打开句柄 (的文件，则无法重命名该目录，但前面) 所述的 batch-oplock 情况除外。

用于重命名 NTFS 数据流的特殊规则：

  • 无法重命名默认目录流。

  • 流的新名称必须以冒号 (：) 开头。

  • 数据流只能在同一文件中重命名。 换句话说，重命名操作不能导致数据流移动到其他文件。

  • 目录上的数据流不能重命名为默认数据流。

  • 如果 ReplaceIfExists 设置为 TRUE，则仅当名称相同的流不存在或为零长度的数据流时，重命名操作才会成功。

  • 允许“重命名”默认数据流，但这不是真正的重命名，因为它会留下零长度的默认数据流。

传递给 ZwSetInformationFile 或FltSetInformationFile 的 FileInformation 缓冲区的大小必须为 >= sizeof (FILE_RENAME_INFORMATION) 加上 FileName 字符串的大小（以字节为单位）。

要求

要求 值
Header ntifs.h (包括 Ntifs.h、Fltkernel.h)

另请参阅

FltSetInformationFile

IRP_MJ_SET_INFORMATION

ZwSetInformationFile