moveFileWithProgressA 函式 (winbase.h)

發行項
03/03/2024

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

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

語法

BOOL MoveFileWithProgressA(
  [in]           LPCSTR             lpExistingFileName,
  [in, optional] LPCSTR             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且 lpNewFileName 為 NULL，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 通訊協定	Yes
SMB 3.0 透明故障轉移 (TFO)	Yes
具有向外延展檔案共用的SMB 3.0 (SO)	Yes
叢集共用磁碟區文件系統 (CsvFS)	Yes
彈性檔案系統 (ReFS)	Yes

CsvF 會針對壓縮檔進行重新導向的 IO。

注意

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

規格需求

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

另請參閱

moveFileWithProgressA 函式 (winbase.h)

語法

參數

傳回值

備註

規格需求

另請參閱

意見反應

意見反應

其他資源