MoveFileWithProgressW 函式（winbase.h）

發行項
11/20/2024

移動檔案或目錄，包括其子系。您可以提供可接收進度通知的回呼函式。

若要以交易作業的形式執行此作業，請使用 MoveFileTransacted 函式。

語法

BOOL MoveFileWithProgressW(
  [in]           LPCWSTR            lpExistingFileName,
  [in, optional] LPCWSTR            lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in]           DWORD              dwFlags
);

參數

[in] lpExistingFileName

本機電腦上現有檔案或目錄的名稱。

如果 dwFlags 指定 MOVEFILE_DELAY_UNTIL_REBOOT，則檔案無法存在於遠端共用上，因為網路可用之前會執行延遲作業。

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

提示

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

[in, optional] lpNewFileName

本機計算機上檔案或目錄的新名稱。

移動檔案時，lpNewFileName 在不同的文件系統或磁碟區上。如果 lpNewFileName 位於另一個磁碟驅動器上，您必須在 dwFlags中設定 MOVEFILE_COPY_ALLOWED 旗標。

移動目錄時，lpExistingFileName 和 lpNewFileName 必須位於相同的磁碟驅動器上。

如果 dwFlags 指定 MOVEFILE_DELAY_UNTIL_REBOOT，lpNewFileNameNULL，MoveFileWithProgress 會在系統重新啟動時註冊 lpExistingFileName 刪除。如果函式無法存取登錄來儲存刪除作業的相關信息，則函式會失敗。如果 lpExistingFileName 參照目錄，則只有在目錄是空的時，系統才會在重新啟動時移除目錄。

提示

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

[in, optional] lpProgressRoutine

CopyProgressRoutine 回呼函式的指標，每次移動檔案的另一個部分時，都會呼叫此函式。如果您提供顯示作業進度的使用者介面，則回呼函式會很有用。此參數可以是 NULL。

[in, optional] lpData

要傳遞至 CopyProgressRoutine 回呼函式的自變數。此參數可以是 NULL。

[in] dwFlags

移動選項。此參數可以是下列其中一或多個值。

價值	意義
MOVEFILE_COPY_ALLOWED 2 （0x2）	如果要將檔案移至不同的磁碟區，函式會使用 CopyFile 和 DeleteFile 函式來模擬移動。如果已成功將檔案複製到不同的磁碟區，且無法刪除源檔，函式會成功讓原始程序檔保持不變。這個值不能與 MOVEFILE_DELAY_UNTIL_REBOOT搭配使用。
MOVEFILE_CREATE_HARDLINK 16 （0x10）	保留供日後使用。
MOVEFILE_DELAY_UNTIL_REBOOT 4 （0x4）	在作業系統重新啟動之前，系統不會移動檔案。系統會在執行 AUTOCHK 之後立即移動檔案，但在建立任何分頁檔案之前。因此，此參數可讓函式從先前的啟動中刪除分頁檔案。只有在進程位於屬於系統管理員群組或 LocalSystem 帳戶的使用者內容中時，才能使用此值。這個值不能與 MOVEFILE_COPY_ALLOWED搭配使用。
MOVEFILE_FAIL_IF_NOT_TRACKABLE 32 （0x20）	如果來源檔案是連結來源，但移動之後無法追蹤檔案，則函式會失敗。如果目的地是使用 FAT 檔案系統格式化的磁碟區，就可能發生這種情況。
MOVEFILE_REPLACE_EXISTING 1 （0x1）	如果名為 lpNewFileName 的檔案存在，函式會將其內容取代為 lpExistingFileName 檔案的內容。如果 lpNewFileName 或 lpExistingFileName 為目錄命名，則無法使用此值。
MOVEFILE_WRITE_THROUGH 8 （0x8）	函式不會傳回，直到檔案實際移至磁碟上為止。設定此值可確保當做複製和刪除作業執行的移動會在函式傳回之前排清到磁碟。排清會在複製作業的結尾發生。如果已設定 MOVEFILE_DELAY_UNTIL_REBOOT，這個值就沒有作用。

傳回值

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

如果函式失敗，傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

在磁碟區之間移動檔案時，如果 lpProgressRoutine 因為使用者取消作業而傳回 PROGRESS_CANCEL，MoveFileWithProgress 會傳回零，而且 getLastError 會傳回 ERROR_REQUEST_ABORTED。現有的檔案會保持不變。

在磁碟區之間移動檔案時，如果 lpProgressRoutine 因為使用者停止作業而傳回 PROGRESS_STOP，MoveFileWithProgress 會傳回零，而且 getLastError 會傳回 ERROR_REQUEST_ABORTED。現有的檔案會保持不變。

言論

MoveFileWithProgress 函式會協調其作業與鏈接追蹤服務，因此可以在行動連結來源時加以追蹤。

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

在 Windows 8 和 Windows Server 2012 中，下列技術支援此功能。

科技	支援
伺服器消息塊（SMB） 3.0 通訊協定	是的
SMB 3.0 透明故障轉移（TFO）	是的
具有向外延展檔案共用的SMB 3.0（SO）	是的
叢集共用磁碟區檔案系統（CsvFS）	是的
復原檔案系統（ReFS）	是的

Csv 會針對壓縮檔執行重新導向的 IO。

注意

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

要求

要求	價值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	winbase.h （包括 Windows.h）
連結庫	Kernel32.lib
DLL	Kernel32.dll