COPYFILE2_MESSAGE 結構 (winbase.h)
傳遞至 CopyFile2ProgressRoutine 回呼函式，其中包含暫止複製作業的相關信息。
語法
typedef struct COPYFILE2_MESSAGE {
COPYFILE2_MESSAGE_TYPE Type;
DWORD dwPadding;
union {
struct {
DWORD dwStreamNumber;
DWORD dwReserved;
HANDLE hSourceFile;
HANDLE hDestinationFile;
ULARGE_INTEGER uliChunkNumber;
ULARGE_INTEGER uliChunkSize;
ULARGE_INTEGER uliStreamSize;
ULARGE_INTEGER uliTotalFileSize;
} ChunkStarted;
struct {
DWORD dwStreamNumber;
DWORD dwFlags;
HANDLE hSourceFile;
HANDLE hDestinationFile;
ULARGE_INTEGER uliChunkNumber;
ULARGE_INTEGER uliChunkSize;
ULARGE_INTEGER uliStreamSize;
ULARGE_INTEGER uliStreamBytesTransferred;
ULARGE_INTEGER uliTotalFileSize;
ULARGE_INTEGER uliTotalBytesTransferred;
} ChunkFinished;
struct {
DWORD dwStreamNumber;
DWORD dwReserved;
HANDLE hSourceFile;
HANDLE hDestinationFile;
ULARGE_INTEGER uliStreamSize;
ULARGE_INTEGER uliTotalFileSize;
} StreamStarted;
struct {
DWORD dwStreamNumber;
DWORD dwReserved;
HANDLE hSourceFile;
HANDLE hDestinationFile;
ULARGE_INTEGER uliStreamSize;
ULARGE_INTEGER uliStreamBytesTransferred;
ULARGE_INTEGER uliTotalFileSize;
ULARGE_INTEGER uliTotalBytesTransferred;
} StreamFinished;
struct {
DWORD dwReserved;
} PollContinue;
struct {
COPYFILE2_COPY_PHASE CopyPhase;
DWORD dwStreamNumber;
HRESULT hrFailure;
DWORD dwReserved;
ULARGE_INTEGER uliChunkNumber;
ULARGE_INTEGER uliStreamSize;
ULARGE_INTEGER uliStreamBytesTransferred;
ULARGE_INTEGER uliTotalFileSize;
ULARGE_INTEGER uliTotalBytesTransferred;
} Error;
} Info;
} COPYFILE2_MESSAGE;
成員
Type
來自 COPYFILE2_MESSAGE_TYPE 列舉的值，用來作為這個結構中 Info 等位的辨別。
| 值 | 意義 |
|---|---|
|
表示已開始複製數據流的單一區塊。 信息位於 Info 等位內的 ChunkStarted 結構中。 |
|
指出數據流單一區塊的複本已完成。 信息位於 Info 等位內的 ChunkFinished 結構中。 |
|
表示已開啟數據流的來源和目的地句柄，而且即將啟動數據流的複本。 信息位於 Info 等位內的 StreamStarted 結構中。 這不表示複本已針對該數據流啟動。 |
|
指出數據流的複製作業已順利完成，或因為從 CopyFile2ProgressRoutine 傳回COPYFILE2_PROGRESS_STOP所致。 信息位於 Info 等位內的 StreamFinished 結構中。 |
|
可能會定期傳送。 信息位於 Info 等位內的 PollContinue 結構中。 |
|
複製作業期間發生錯誤。 信息位於 Info 等位內的 Error 結構中。 |
dwPadding
Info
Info.ChunkStarted
如果 Type 成員設定為 COPYFILE2_CALLBACK_CHUNK_STARTED ( 1) ，則會選取此結構。
Info.ChunkStarted.dwStreamNumber
指出檔案內即將複製的數據流。 用來識別檔案內數據流的值會從 1 (1 開始) ，而且一律高於該檔案的任何先前數據流。
Info.ChunkStarted.dwReserved
此成員會保留供內部使用。
Info.ChunkStarted.hSourceFile
來源數據流的句柄。
Info.ChunkStarted.hDestinationFile
目的地數據流的句柄。
Info.ChunkStarted.uliChunkNumber
指出目前數據流內即將複製的區塊。 用於區塊的值會從零開始， (0) ，而且一律高於目前數據流上任何先前區塊的值。
Info.ChunkStarted.uliChunkSize
複製區塊的大小，以位元組為單位。
Info.ChunkStarted.uliStreamSize
目前數據流的大小，以位元組為單位。
Info.ChunkStarted.uliTotalFileSize
此檔案的所有數據流大小，以位元組為單位。
Info.ChunkFinished
如果 Type 成員設定為 COPYFILE2_CALLBACK_CHUNK_FINISHED ( 2) ，則會選取此結構。
ChunkFinished.dwReserved
此成員會保留供內部使用。
Info.ChunkFinished.dwStreamNumber
指出檔案內即將複製的數據流。 用來識別檔案內數據流的值會從 1 (1 開始) ，而且一律高於該檔案的任何先前數據流。
Info.ChunkFinished.dwFlags
Info.ChunkFinished.hSourceFile
來源數據流的句柄。
Info.ChunkFinished.hDestinationFile
目的地數據流的句柄。
Info.ChunkFinished.uliChunkNumber
指出目前數據流內的區塊正在處理中。 用於區塊的值會從零開始， (0) ，而且一律高於目前數據流上任何先前區塊的值。
Info.ChunkFinished.uliChunkSize
複製區塊的大小，以位元組為單位。
Info.ChunkFinished.uliStreamSize
目前數據流的大小，以位元組為單位。
Info.ChunkFinished.uliStreamBytesTransferred
到目前為止，針對此數據流複製的總位元組數。
Info.ChunkFinished.uliTotalFileSize
此檔案的所有數據流大小，以位元組為單位。
Info.ChunkFinished.uliTotalBytesTransferred
到目前為止，此檔案複製的位元組總數。
Info.StreamStarted
如果 Type 成員設定為 COPYFILE2_CALLBACK_STREAM_STARTED ( 3) ，則會選取此結構。
Info.StreamStarted.dwStreamNumber
指出檔案內即將複製的數據流。 用來識別檔案內數據流的值會從 1 (1 開始) ，而且一律高於該檔案的任何先前數據流。
Info.StreamStarted.dwReserved
此成員會保留供內部使用。
Info.StreamStarted.hSourceFile
來源數據流的句柄。
Info.StreamStarted.hDestinationFile
目的地數據流的句柄。
Info.StreamStarted.uliStreamSize
目前數據流的大小，以位元組為單位。
Info.StreamStarted.uliTotalFileSize
此檔案的所有數據流大小，以位元組為單位。
Info.StreamFinished
如果 Type 成員設定為 COPYFILE2_CALLBACK_STREAM_FINISHED ( 4) ，則會選取此結構。
Info.StreamFinished.dwStreamNumber
指出檔案內即將複製的數據流。 用來識別檔案內數據流的值會從 1 (1 開始) ，而且一律高於該檔案的任何先前數據流。
Info.StreamFinished.dwReserved
此成員會保留供內部使用。
Info.StreamFinished.hSourceFile
來源數據流的句柄。
Info.StreamFinished.hDestinationFile
目的地數據流的句柄。
Info.StreamFinished.uliStreamSize
目前數據流的大小，以位元組為單位。
Info.StreamFinished.uliStreamBytesTransferred
到目前為止，針對此數據流複製的總位元組數。
Info.StreamFinished.uliTotalFileSize
此檔案的所有數據流大小，以位元組為單位。
Info.StreamFinished.uliTotalBytesTransferred
到目前為止，此檔案複製的位元組總數。
Info.PollContinue
如果 Type 成員設定為 COPYFILE2_CALLBACK_POLL_CONTNUE ( 5) ，則會選取此結構。
Info.PollContinue.dwReserved
此成員會保留供內部使用。
Info.Error
如果 Type 成員設定為 COPYFILE2_CALLBACK_ERROR ( 6) ，則會選取此結構。
Info.Error.CopyPhase
COPYFILE2_COPY_PHASE 列舉的值 ，指出錯誤時複本的目前階段。
Info.Error.dwStreamNumber
錯誤時正在處理的數據流數目。
Info.Error.hrFailure
指出問題的值。
Info.Error.dwReserved
此成員會保留供內部使用。
Info.Error.uliChunkNumber
指出錯誤時正在處理目前數據流內的區塊。 用於區塊的值會從零開始， (0) ，而且一律高於目前數據流上任何先前區塊的值。
Info.Error.uliStreamSize
正在處理的數據流大小，以位元組為單位。
Info.Error.uliStreamBytesTransferred
已針對正在處理的數據流成功傳輸的位元元組數目。
Info.Error.uliTotalFileSize
正在處理之檔案總數的大小，以位元組為單位。
Info.Error.uliTotalBytesTransferred
已針對整個複製作業成功傳輸的位元元組數目。
備註
若要編譯使用 COPYFILE2_MESSAGE 結構的應用程式，請將_WIN32_WINNT宏定義為 0x0601 或更新版本。 如需詳細資訊，請參閱 使用 Windows 標頭。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows 8 [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows Server 2012 [傳統型應用程式 |UWP 應用程式] |
| 標頭 | winbase.h (包含 Windows.h) |
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應