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) | 將檔案重新命名為新目錄時，隱藏與檔案記憶體保留標識符屬性相關的任何繼承規則。 |
| 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 IRP_MJ_SET_INFORMATION。
文件系統迷你篩選必須使用 FltSetInformationFile，而不是 ZwSetInformationFile 來重新命名檔案。
重新命名檔案需要刪除檔案的存取權，才能從目前的父目錄移除目錄專案，以及適當的存取權，以便在新的父目錄檔案中建立新專案。
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 字元串位元組的大小。
規格需求
| 需求 | 值 |
|---|---|
| 標頭 | ntifs.h (包含 Ntifs.h、Fltkernel.h) |