Delphi WinAPI CopyFile、CopyFileEx、CopyFileTransacted -复制文件

Delphi WinAPI CopyFile、CopyFileEx、CopyFileTransacted -复制文件

1、CopyFile 

功能描述：将现有文件复制到新文件。CopyFileEx函数提供了两个附加功能。CopyFileEx可以在每次复制操作的一部分完成时调用指定的回调函数，并且可以在复制操作期间取消CopyFileEx。若要将此操作作为事务处理操作执行，请使用CopyFileTransacted函数。

函数原型：

BOOL CopyFile(
  LPCTSTR lpExistingFileName, {源文件}  //现有文件的名称。
  LPCTSTR lpNewFileName,   {目标文件}  //新文件的名称
  BOOL    bFailIfExists   {true 目标存在则跳过，false 直接覆盖} //如果此参数为TRUE，且lpNewFileName指定的新文件已存在，则函数将失败。如果此参数为FALSE且新文件已存在，则函数将覆盖现有文件并成功。
);

返回值：如果函数成功，则返回值为非零。如果函数失败，返回值为零。

Delphi 示例：

var
  yFile,NewFile:string;
begin
  yFile :='c:\text.txt';
  NewFile:='c:\temp\test.txt';
  if CopyFile(PChar(yFile), PChar(NewFile), True) then
    ShowMessage('复制成功') else ShowMessage('复制失败'); 
end;

2、CopyFileEx

功能描述：将现有文件复制到新文件，并通过 回调函数 通知应用程序其 进度。若要将此操作作为事务处理操作执行，请使用CopyFileTransacted函数。

函数原型：

BOOL CopyFileEx(
  LPCSTR             lpExistingFileName,
  LPCSTR             lpNewFileName,
  LPPROGRESS_ROUTINE lpProgressRoutine,  //LPPROGRESS_ROUTINE类型的回调函数的地址，每次复制文件的另一部分时调用该函数。此参数可以为NULL。
  LPVOID             lpData,  //要传递给回调函数的参数。此参数可以为NULL。
  LPBOOL             pbCancel,  //如果在复制操作期间将此标志设置为TRUE，则该操作将被取消。否则，复制操作将继续完成。
  DWORD              dwCopyFlags  //指定如何复制文件的标志。
);

参数说明：

　　dwCopyFlags  //指定如何复制文件的标志，可以以下的值：

• • OPY_FILE_ALLOW_DECRYPTED_DESTINATION  //即使目标副本无法加密，复制加密文件的尝试也会成功。
  • COPY_FILE_COPY_SYMLINK  //如果源文件是符号链接，则目标文件也是指向源符号链接指向的同一文件的符号链接。
  • COPY_FILE_FAIL_IF_EXISTS  //如果目标文件已存在，复制操作将立即失败。
  • COPY_FILE_NO_BUFFERING  //复制操作使用无缓冲I/O执行，绕过系统I/O缓存资源。建议用于非常大的文件传输。Windows Server 2003和Windows XP：不支持此值。
  • COPY_FILE_OPEN_SOURCE_FOR_WRITE  //将复制该文件，并打开原始文件进行写访问。
  • COPY_FILE_RESTARTABLE  //如果复制失败，将在目标文件中跟踪复制的进度。通过为lpExistingFileName和lpNewFileName指定与失败调用中使用的值相同的值，可以在以后重新启动失败的副本。这会显著降低复制操作的速度，因为在复制操作期间，新文件可能会被刷新多次。
  • COPY_FILE_REQUEST_COMPRESSED_TRAFFIC  //请求底层传输通道在复制操作期间压缩数据。可能并非所有介质都支持该请求，在这种情况下，该请求将被忽略。压缩属性和参数（计算复杂度、内存使用）无法通过该API进行配置，并且在不同的操作系统版本之间可能会发生变化。

返回值：

• 如果函数成功，则返回值为非零。
• 如果函数失败，返回值为零。要获取扩展错误信息，请调用GetLastError。
• 如果lpProgressRoutine由于用户取消操作而返回PROGRESS_CANCEL，CopyFileEx将返回零，GetLastError将返回ERROR_REQUEST_ABORTED。在这种情况下，部分复制的目标文件将被删除。
• 如果lpProgressRoutine由于用户停止操作而返回PROGRESS_STOP，CopyFileEx将返回零，GetLastError将返回ERROR_REQUEST_ABORTED。在这种情况下，部分复制的目标文件保持不变。

2.1 关于LPPROGRESS_ROUTINE回调函数：

LPPROGRESS_ROUTINE LpprogressRoutine;

DWORD LpprogressRoutine(
  [in]           LARGE_INTEGER TotalFileSize, //文件的总大小（以字节为单位）。
  [in]           LARGE_INTEGER TotalBytesTransferred,  //自复制操作开始以来，从源文件传输到目标文件的字节总数。
  [in]           LARGE_INTEGER StreamSize,  //当前文件流的总大小（以字节为单位）。
  [in]           LARGE_INTEGER StreamBytesTransferred,  //自复制操作开始以来，当前流中已从源文件传输到目标文件的字节总数。
  [in]           DWORD dwStreamNumber,  //当前流的句柄。 首次调用 CopyProgressRoutine 时，流号为 1。
  [in]           DWORD dwCallbackReason,  //调用 CopyProgressRoutine 的原因。 
  [in]           HANDLE hSourceFile,  //源文件的句柄。
  [in]           HANDLE hDestinationFile,  //目标文件的句柄
  [in, optional] LPVOID lpData  //由 CopyFileEx 传递给 CopyProgressRoutine 的参数。
)

返回值：

• PROGRESS_CANCEL //1 取消复制操作并删除目标文件。
• PROGRESS_CONTINUE //0 继续复制操作。
• PROGRESS_QUIET //3 继续复制操作，但停止调用 CopyProgressRoutine 以报告进度。
• PROGRESS_STOP //2 停止复制操作。 以后可以重启它。

2.1.1 关于调用CopyProgressRoutine的原因的参数取值：

• CALLBACK_CHUNK_FINISHED //0x00000000 复制了数据文件的另一部分。
• CALLBACK_STREAM_SWITCH //0x00000001 另一个流已创建，即将复制。 这是首次调用回调例程时给定的回调原因。

　

 

3、CopyFileTransacted

功能描述：将现有文件作为事务处理操作复制到新文件，并通过回调函数通知应用程序其进度。

函数原型：

BOOL CopyFileTransacted(
  LPCSTR             lpExistingFileName,
  LPCSTR             lpNewFileName,
  LPPROGRESS_ROUTINE lpProgressRoutine,
  LPVOID             lpData,
  LPBOOL             pbCancel,
  DWORD              dwCopyFlags,
  HANDLE             hTransaction
);

参数说明：以后有时间补充

 

 

 

创建时间：2020.08.31　　更新时间：2022.03.29  、2024.03.27