MoveFileTransactedA 函式 (winbase.h)

  • 發行項

[Microsoft 強烈建議開發人員利用替代方式來達成應用程式的需求。 許多針對 TxF 開發的案例，都可以透過更簡單且更容易使用的技巧來達成。 此外，未來版本的 Microsoft Windows 可能無法使用 TxF。 如需詳細資訊，以及 TxF 的替代方案，請參閱 使用交易式 NTFS 的替代方案。

移動現有的檔案或目錄，包括其子系，做為交易作業。

語法

BOOL MoveFileTransactedA(
  [in]           LPCSTR             lpExistingFileName,
  [in, optional] LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in]           DWORD              dwFlags,
  [in]           HANDLE             hTransaction
);

參數

[in] lpExistingFileName

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

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

提示

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

[in, optional] lpNewFileName

檔案或目錄的新名稱。 新名稱不得已存在。 新的檔案可能位於不同的文件系統或磁碟驅動器上。 新的目錄必須位於相同的磁碟驅動器上。

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

提示

從 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_REPLACE_EXISTING
1 (0x1)
如果名為 lpNewFileName 的檔案存在，函式會以 lpExistingFileName 檔案的內容取代其內容。

如果 lpNewFileName 或 lpExistingFileName 為目錄命名，則無法使用此值。
MOVEFILE_WRITE_THROUGH
8 (0x8)
呼叫 MoveFileTransacted 表示完成認可作業時，移動檔案作業已完成。 不需要此旗標;如果指定此旗標，則不會有任何負面影響，而不是作業速度變慢。 函式不會傳回，直到檔案實際移動於磁碟上為止。

設定此值可確保在函式傳回之前，將執行為複製和刪除作業的移動排清到磁碟。 排清會在複製作業結束時發生。

如果 已設定MOVEFILE_DELAY_UNTIL_REBOOT， 這個值就不會有任何作用。

[in] hTransaction

交易的句柄。 CreateTransaction 函式會傳回這個句柄。

傳回值

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

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

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

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

備註

如果 dwFlags 參數指定 MOVEFILE_DELAY_UNTIL_REBOOT， 如果 MoveFileTransacted 無法存取登錄，就會失敗。 函式會在下列登錄值中，以交易方式儲存要在重新啟動時重新命名的檔案位置： HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\控制\會話管理員\PendingFileRenameOperations

此登錄值的類型為 REG_MULTI_SZ。 每個重新命名作業都會儲存下列其中一個 NULL 終止的字串，視重新命名是否為刪除而定：

szDstFile\0\0

szSrcFile\0szDstFile\0

字串 szDstFile\0\0 表示在重新啟動時要刪除 szDstFile 檔案。

字串 szSrcFile\0szDstFile\0 表示 szSrcFile 在重新啟動時要重新命名 szDstFile 。

注意 雖然 \0\0 在技術上不允許 在REG_MULTI_SZ 節點中，但可能會因為檔案被視為重新命名為 Null 名稱。
 
系統會使用這些登錄專案，以與發出作業的順序相同，在重新啟動時完成作業。 如需使用 MOVEFILE_DELAY_UNTIL_REBOOT 旗標的詳細資訊，請參閱 MoveFileWithProgress。

如果檔案跨磁碟區移動， MoveFileTransacted 不會移動檔案的安全性描述符。 檔案會指派目的地目錄中的預設安全性描述元。

如果您指定MOVEFILE_FAIL_IF_NOT_TRACKABLE旗標 ， 此函式一律會失敗;TxF 不支持追蹤。

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

技術 支援
伺服器消息塊 (SMB) 3.0 通訊協定 No
SMB 3.0 透明故障轉移 (TFO) No
具有向外延展檔案共用的SMB 3.0 (SO) No
叢集共用磁碟區文件系統 (CsvFS) No
彈性檔案系統 (ReFS) No
 

SMB 3.0 不支援 TxF。

規格需求

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

另請參閱

CopyFileTransacted

檔案管理功能

MoveFileWithProgress

交易式 NTFS