replaceFileW 函式 (winbase.h)

發行項
03/03/2024

以另一個檔案取代一個檔案，並使用建立源文件備份複本的選項。取代檔案會假設取代的檔名及其身分識別。

語法

BOOL ReplaceFileW(
  [in]           LPCWSTR lpReplacedFileName,
  [in]           LPCWSTR lpReplacementFileName,
  [in, optional] LPCWSTR lpBackupFileName,
  [in]           DWORD   dwReplaceFlags,
                 LPVOID  lpExclude,
                 LPVOID  lpReserved
);

參數

[in] lpReplacedFileName

要取代的檔名。

根據預設，名稱限製為MAX_PATH個字元。若要將此限制延伸至 32,767 寬字元，請在路徑前面加上 “\\？\”。如需詳細資訊，請參閱命名檔案、路徑與命名空間。

提示

從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需在前面加上 “\\？\”。如需詳細資訊，請參閱命名檔案、路徑和命名空間的一節。

此檔案會以 GENERIC_READ、 DELETE 和 SYNCHRONIZE 存取權限開啟。共用模式 FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE。

呼叫端必須具有要取代之檔案的寫入許可權。如需詳細資訊，請參閱檔案安全性和訪問許可權。

[in] lpReplacementFileName

將取代 lpReplacedFileName 檔案的檔名。

提示

從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需在前面加上 “\\？\”。如需詳細資訊，請參閱命名檔案、路徑和命名空間的一節。

函式會嘗試使用 SYNCHRONIZE、 GENERIC_READ、 GENERIC_WRITE、 DELETE和 WRITE_DAC 訪問許可權來開啟此檔案，以便保留所有屬性和 ACL。如果失敗，函式會嘗試使用 SYNCHRONIZE、 GENERIC_READ、 DELETE和 WRITE_DAC 訪問許可權來開啟檔案。未指定共用模式。

[in, optional] lpBackupFileName

將做為 lpReplacedFileName 檔案備份複本的檔名。如果此參數為 NULL，則不會建立備份檔。如需備份文件的實作詳細數據，請參閱一節。

提示

從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需在前面加上 “\\？\”。如需詳細資訊，請參閱命名檔案、路徑和命名空間的一節。

[in] dwReplaceFlags

取代選項。此參數可以是下列一或多個值。

值	意義
REPLACEFILE_WRITE_THROUGH 0x00000001	不支援這個值。
REPLACEFILE_IGNORE_MERGE_ERRORS 0x00000002	忽略將資訊合併 (時發生的錯誤，例如屬性和 ACL) 從取代的檔案到取代檔案。因此，如果您指定此旗標且沒有 WRITE_DAC 存取權，則函式會成功，但不會保留 ACL。
REPLACEFILE_IGNORE_ACL_ERRORS 0x00000004	忽略將 ACL 資訊從取代的檔案合併至取代檔案時所發生的錯誤。因此，如果您指定此旗標且沒有 WRITE_DAC 存取權，則函式會成功，但不會保留 ACL。若要編譯使用此值的應用程式，請將_WIN32_WINNT宏定義為 0x0600 或更新版本。 Windows Server 2003 和 Windows XP：不支援這個值。

lpExclude

保留供未來使用。

lpReserved

保留供未來使用。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。以下是此函式的可能錯誤碼。

傳回碼/值	Description
ERROR_UNABLE_TO_MOVE_REPLACEMENT 1176 (0x498)	無法重新命名取代檔案。如果指定了 lpBackupFileName ，取代和取代的檔案會保留其源檔名稱。否則，已取代的檔案已不存在，且取代檔案會以其原始名稱存在。
ERROR_UNABLE_TO_MOVE_REPLACEMENT_2 1177 (0x499)	無法移動取代檔案。取代檔案仍然存在於原始名稱下;不過，它已從它所取代的檔案繼承檔案數據流和屬性。要取代的檔案仍會以不同的名稱存在。如果指定 lpBackupFileName ，它會是已取代檔案的名稱。
ERROR_UNABLE_TO_REMOVE_REPLACED 1175 (0x497)	無法刪除已取代的檔案。已取代和取代的檔案會保留其源檔名稱。

如果傳回任何其他錯誤，例如 ERROR_INVALID_PARAMETER，取代和取代的檔案會保留其源檔名稱。在此案例中，備份檔不存在，而且不保證取代檔案會繼承已取代檔案的所有屬性和數據流。

備註

提示從 Windows 10 1607 版開始，針對此函式的 unicode 版本 (ReplaceFileW) ，您可以選擇移除MAX_PATH限制。如需詳細資訊，請參閱命名檔案、路徑和命名空間的一節。

ReplaceFile 函式會結合單一函式內的數個步驟。應用程式可以呼叫 ReplaceFile ，而不是呼叫個別的函式，將數據儲存至新檔案、使用暫存名稱重新命名源檔、將新檔案重新命名為與源檔同名，以及刪除源檔。另一個優點是 ReplaceFile 不僅會複製新的檔案數據，也會保留源檔的下列屬性：

建立時間
簡短檔名
物件識別碼
DACL
安全性資源屬性
加密
壓縮
取代檔案中還沒有具名數據流

例如，如果取代檔案已加密，但未加密已取代的檔案，則產生的檔案不會加密。

Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 在 Windows 8 和 Windows Server 2012 之前，不會保留源文件的安全性資源屬性 ( ATTRIBUTE_SECURITY_INFORMATION) 。

注意

如果使用選擇性抹除來保護取代檔案，則取代的檔案將會受到取代檔案的企業標識符保護。

產生的檔案具有與取代檔案相同的檔案標識符。

備份檔、已取代的檔案和取代檔案必須全部位於相同的磁碟區上。

若要刪除或重新命名檔案，您必須擁有檔案的刪除許可權，或刪除父目錄中的子許可權。如果您設定目錄具有刪除和刪除子系和新檔案的 DACL 以外的所有存取權，則您應該能夠建立檔案，而不需要刪除它。不過，您可以接著建立檔案，並在建立檔案時，取得在傳回給您的句柄上要求的所有存取權。如果您在建立檔案時要求刪除許可權，您可以使用該句柄刪除或重新命名檔案，但不能與任何其他檔案一起重新命名。

注意

winbase.h 標頭會將 ReplaceFile 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	winbase.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll