共用方式為

winbase.h (COPYFILE2_EXTENDED_PARAMETERS_V2 結構)

  • 發行項

包含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 標頭