共用方式為

COPYFILE2_EXTENDED_PARAMETERS_V2結構 （winbase.h）

  • 發行項

包含 CopyFile2 函式 COPYFILE2_EXTENDED_PARAMETERS 結構以外的其他功能。

語法

typedef struct COPYFILE2_EXTENDED_PARAMETERS_V2 {
  DWORD                         dwSize;
  DWORD                         dwCopyFlags;
  BOOL                          *pfCancel;
  PCOPYFILE2_PROGRESS_ROUTINE   pProgressRoutine;
  PVOID                         pvCallbackContext;
  DWORD                         dwCopyFlagsV2;
  ULONG                         ioDesiredSize;
  ULONG                         ioDesiredRate;
  LPPROGRESS_ROUTINE            pProgressRoutineOld;
  PCOPYFILE2_CREATE_OPLOCK_KEYS SourceOplockKeys;
#if ...
  PVOID                         reserved[6];
#elif
  PVOID                         reserved[7];
#else
  PVOID                         reserved[8];
#endif
} COPYFILE2_EXTENDED_PARAMETERS_V2;

成員

dwSize

包含這個結構的大小，sizeof(COPYFILE2_EXTENDED_PARAMETERS_V2)。

dwCopyFlags

包含零個或多個這些旗標值的組合。

價值 意義
COPY_FILE_FAIL_IF_EXISTS
0x00000001		 如果目的地檔案存在，複製作業會立即失敗。 如果檔案或目錄具有目的地名稱，則 CopyFile2 函數呼叫將會失敗，並 HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS) 或 HRESULT_FROM_WIN32(ERROR_FILE_EXISTS)。 如果同時指定 COPY_FILE_RESUME_FROM_PAUSE，則只有在目的地檔案沒有有效的重新啟動標頭時，才會觸發失敗。
COPY_FILE_RESTARTABLE
0x00000002		 如果再次使用相同的來源和目的地檔名，檔案會以可以重新啟動的方式複製。 這是較慢的。
COPY_FILE_OPEN_SOURCE_FOR_WRITE
0x00000004		 檔案會複製並開啟原始程序檔以供寫入存取。
COPY_FILE_ALLOW_DECRYPTED_DESTINATION
0x00000008		 即使目的地檔案無法加密，也會嘗試複製。
COPY_FILE_COPY_SYMLINK
0x00000800		 如果來源檔案是符號連結，目的地檔案也是指向與來源符號連結相同的檔案的符號連結。
COPY_FILE_NO_BUFFERING
0x00001000		 複製是使用未壓縮的 I/O 來執行，略過系統快取資源。 建議針對非常大的檔案復本使用此旗標。 不建議暫停使用此旗標的複本。
COPY_FILE_REQUEST_SECURITY_PRIVILEGES
0x00002000		 嘗試複製，並指定來源檔案的 ACCESS_SYSTEM_SECURITY，併為目的地檔案指定 ACCESS_SYSTEM_SECURITY \| WRITE_DAC \| WRITE_OWNER。 如果拒絕這些要求，存取要求將會縮減為授與存取權的最高許可權等級。 如需詳細資訊，請參閱 SACL 存取權。 這可用來允許 CopyFile2ProgressRoutine 回呼執行需要較高許可權的作業，例如複製檔案的安全性屬性。
COPY_FILE_RESUME_FROM_PAUSE
0x00004000		 會檢查目的地檔案，以查看是否使用 COPY_FILE_RESTARTABLE複製。 如果是，則會繼續複製。 如果不是，則會完整複製檔案。
COPY_FILE_NO_OFFLOAD
0x00040000		 請勿嘗試使用 Windows 複製卸除機制。 這通常不建議使用。
COPY_FILE_IGNORE_EDP_BLOCK
0x00400000		 如果目的地文件系統支援，則應該在目的地上複製並加密檔案，而不是封鎖檔案。 Windows 10 和更新版本支援 。
COPY_FILE_IGNORE_SOURCE_ENCRYPTION
0x00800000		 忽略來源檔案的加密狀態。 Windows 10 和更新版本支援 。
COPY_FILE_DONT_REQUEST_DEST_WRITE_DAC
0x02000000		 請勿要求目的地檔案存取WRITE_DAC。 Windows 10 和更新版本支援 。
COPY_FILE_OPEN_AND_COPY_REPARSE_POINT
0x00200000		 不論類型為何，一律複製重新分析點。 呼叫者有責任瞭解重新分析點的意義。 Windows 10 支援組建 19041 和更新版本。
COPY_FILE_DIRECTORY
0x00000080		 指出來源檔案是目錄檔案。 提供時，會使用 FILE_OPEN_FOR_BACKUP_INTENT開啟原始程序檔。 目錄檔案會有其替代數據流、重新分析點資訊，以及像一般檔案一樣複製的 EA。 Windows 10 支援組建 19041 和更新版本。
COPY_FILE_SKIP_ALTERNATE_STREAMS
0x00008000		 請勿複製替代數據流。 Windows 10 支援組建 19041 和更新版本。
COPY_FILE_DISABLE_PRE_ALLOCATION
0x04000000		 在執行複製之前，請勿預先配置目的地檔案大小。 Windows 10 支援組建 19041 和更新版本。
COPY_FILE_ENABLE_LOW_FREE_SPACE_MODE
0x08000000		 啟用 LowFreeSpace 模式。 不會使用重疊的 I/O。 不會嘗試 ODX 和 SMB 卸除。 Windows 10 支援組建 19041 和更新版本。
COPY_FILE_REQUEST_COMPRESSED_TRAFFIC
0x10000000		 要求基礎傳輸通道在複製作業期間壓縮數據。 所有媒體都可能不支援要求，在此情況下會予以忽略。 壓縮屬性和參數（計算複雜度、記憶體使用量）無法透過此 API 設定，而且可能會在不同的 OS 版本之間變更。

此旗標是在 Windows 10 版本 1903 和 Windows Server 2022 中引進的。 在 Windows 10 上，SMB 共用上的檔案支援旗標，其中交涉 SMB 通訊協定版本為 SMB v3.1.1 或更新版本。
COPY_FILE_ENABLE_SPARSE_COPY
0x20000000		 啟用在複製期間保留檔案的疏鬆狀態。 Windows 11 中支援組建 22H2 和更新版本。

pfCancel

如果此旗標設定為在複製作業期間 TRUE，則會取消複製作業。

pProgressRoutine

PCOPYFILE2_PROGRESS_ROUTINE 型別回呼函式的選擇性位址，會在每次複製檔案的另一個部分時呼叫。 此參數可以是 NULL。 如需進度回呼函式的詳細資訊，請參閱 CopyFile2ProgressRoutine 回呼函式。 如果同時提供 pProgressRoutineOld 和 pProgressRoutine，pProgressRoutineOld 優先。

pvCallbackContext

要傳遞至 CopyFile2ProgressRoutine 之應用程式特定內容資訊的指標。

dwCopyFlagsV2

包含零個或多個這些旗標值的組合。

價值 意義
COPY_FILE2_V2_DONT_COPY_JUNCTIONS
0x00000001		 停用複製連接點。

ioDesiredSize

自選。 每個 I/O 作業的要求大小（以位元組為單位）（也就是複製檔案時一個讀取/寫入週期）。 如果記憶體不足，可能會降低此狀況。 如果為零，則會使用預設大小。 如果也提供 ioDesiredRate，可能會忽略此專案

ioDesiredRate

自選。 要求的平均 I/O 速率，每秒以 KB 為單位。 如果為零，則會儘快執行複本。

pProgressRoutineOld

SourceOplockKeys

reserved[6]

reserved[7]

reserved[8]

pProgressRoutineOld。 自選。 型別為 LPPROGRESS_ROUTINE 的舊式回呼函式位址，每次複製檔案的另一個部分時，都會呼叫該函式。 此參數可以是 NULL。 如需進度回呼函式的詳細資訊，請參閱 LPPROGRESS_ROUTINE 回呼。 如果同時提供 pProgressRoutineOld 和 pProgressRoutine，pProgressRoutineOld 優先。

言論

若要編譯使用此結構的應用程式，請將 _WIN32_WINNT 巨集定義為 _WIN32_WINNT_WIN8 或更新版本。 如需詳細資訊，請參閱使用 Windows 標頭。

要求

要求 價值
最低支援的用戶端 Windows 11 [傳統型應用程式 |UWP 應用程式]
支援的最低伺服器 Windows Server 2012 [傳統型應用程式 |UWP 應用程式]
標頭 winbase.h （包括 Windows.h）

另請參閱

CopyFile2

COPYFILE2_EXTENDED_PARAMETERS

CopyFile2ProgressRoutine

檔案管理結構

LPPROGRESS_ROUTINE

使用 Windows 標頭