CopyFileTransactedA 函式 （winbase.h）

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

將現有檔案複製到新檔案做為交易作業，透過回呼函式通知其進度。

語法

BOOL CopyFileTransactedA(
  [in]           LPCSTR             lpExistingFileName,
  [in]           LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in, optional] LPBOOL             pbCancel,
  [in]           DWORD              dwCopyFlags,
  [in]           HANDLE             hTransaction
);

參數

[in] lpExistingFileName

現有檔案的名稱。

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

如果 lpExistingFileName 不存在，CopyFileTransacted 函式會失敗，而 getLastError 函式 會傳回 ERROR_FILE_NOT_FOUND。

檔案必須位於本機計算機上;否則，函式會失敗，且最後一個錯誤碼會設定為 ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE。

[in] lpNewFileName

新檔案的名稱。

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

[in, optional] lpProgressRoutine

每次複製檔案另一個部分時，呼叫類型為 LPPROGRESS_ROUTINE 的回呼函式位址。 此參數可以是 NULL。 如需進度回呼函式的詳細資訊，請參閱 CopyProgressRoutine 函式。

[in, optional] lpData

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

[in, optional] pbCancel

如果此旗標設定為在複製作業期間 TRUE，則會取消作業。 否則，複製作業將會繼續完成。

[in] dwCopyFlags

指定要如何複製檔案的旗標。 此參數可以是下列值的組合。

[in] hTransaction

交易的句柄。 此句柄是由 createTransaction 函式 傳回。

傳回值

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

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

如果 lpProgressRoutine 因為使用者取消作業而傳回 PROGRESS_CANCEL，CopyFileTransacted 會傳回零，而且 getLastError 會傳回 ERROR_REQUEST_ABORTED。 在此情況下，會刪除部分複製的目的地檔案。

如果 lpProgressRoutine 因為使用者停止作業而傳回 PROGRESS_STOP，CopyFileTransacted 會傳回零，而且 getLastError 會傳回 ERROR_REQUEST_ABORTED。 在此情況下，部分複製的目的地檔案會保持不變。

如果您嘗試使用已回覆之交易的句柄呼叫此函式，CopyFileTransacted 會傳回 ERROR_TRANSACTION_NOT_ACTIVE 或 ERROR_INVALID_TRANSACTION。

言論

此函式會保留擴充屬性、OLE 結構化記憶體、NTFS 檔案系統替代數據流、安全性屬性和檔案屬性。

Windows 7、Windows Server 2008 R2、Windows Server 2008 和 Windows Vista：現有檔案的安全性資源屬性（ATTRIBUTE_SECURITY_INFORMATION），直到 Windows 8 和 Windows Server 2012 才會複製到新檔案。

如果目的地檔案已經存在，且已設定 FILE_ATTRIBUTE_HIDDEN 或 FILE_ATTRIBUTE_READONLY 屬性，則此函式會失敗並 ERROR_ACCESS_DENIED。

TxF 不支援加密的檔案。

如果指定 COPY_FILE_COPY_SYMLINK，則會套用下列規則：

• 如果來源檔案是符號連結，則會複製符號連結，而不是目標檔案。
• 如果來源檔案不是符號連結，則行為沒有變更。
• 如果目的地檔案是現有的符號連結，則會覆寫符號連結，而不是目標檔案。
• 如果同時指定 COPY_FILE_FAIL_IF_EXISTS，而且目的地檔案是現有的符號連結，則作業在所有情況下都會失敗。

• 如果同時指定 COPY_FILE_FAIL_IF_EXISTS，而且目的地檔案是現有的符號連結，則只有在符號鏈接的目標存在時，作業才會失敗。
• 如果未指定 COPY_FILE_FAIL_IF_EXISTS，則行為沒有變更。

TxF 不支持連結追蹤。

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

請注意，SMB 3.0 不支援 TxF。

要求

另請參閱

CopyProgressRoutine

CreateFileTransacted

檔案屬性常數

檔案管理功能

MoveFileTransacted

符號連結

交易式NTFS