CopyFile2 函数 (winbase.h)

  • 项目

将现有文件复制到新文件，并通过回调函数向应用程序通知此操作的进度。

语法

HRESULT CopyFile2(
  [in]           PCWSTR                        pwszExistingFileName,
  [in]           PCWSTR                        pwszNewFileName,
  [in, optional] COPYFILE2_EXTENDED_PARAMETERS *pExtendedParameters
);

参数

[in] pwszExistingFileName

现有文件的名称。

若要将此限制扩展到 32，767 个宽字符，请在路径前面添加“\？”。 有关详细信息，请参阅命名文件、路径和命名空间。

提示从 Windows 10 版本 1607 开始，可以选择删除MAX_PATH字符限制，而无需在前面添加“\\？\”。 有关详细信息，请参阅 命名文件、路径和命名空间 的“最大路径限制”部分。
 
如果 lpExistingFileName 不存在， 则 CopyFile2 函数失败将 HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)返回 。

[in] pwszNewFileName

新文件的名称。

若要将此限制扩展到 32，767 个宽字符，请在路径前面添加“\？”。 有关详细信息，请参阅命名文件、路径和命名空间。

提示从 Windows 10 版本 1607 开始，可以选择删除MAX_PATH字符限制，而无需在前面添加“\\？\”。 有关详细信息，请参阅 命名文件、路径和命名空间 的“最大路径限制”部分。
 

[in, optional] pExtendedParameters

COPYFILE2_EXTENDED_PARAMETERS结构的可选地址。

返回值

如果函数成功，则当传递给 SUCCEEDED 宏时，返回值将返回 TRUE。

返回代码 说明
S_OK
 复制操作已成功完成。
HRESULT_FROM_WIN32 (ERROR_REQUEST_PAUSED)
复制操作因 CopyFile2ProgressRoutine 回调函数返回COPYFILE2_PROGRESS_PAUSE暂停。
HRESULT_FROM_WIN32 (ERROR_REQUEST_ABORTED)
复制操作因 copyFile2ProgressRoutine 回调函数COPYFILE2_PROGRESS_CANCEL或COPYFILE2_PROGRESS_STOP返回而暂停。
HRESULT_FROM_WIN32 (ERROR_ALREADY_EXISTS)
通过 pExtendedParameters 参数传递的 COPYFILE2_EXTENDED_PARAMETERS 结构的 dwCopyFlags 成员包含 COPY_FILE_FAIL_IF_EXISTS 标志，并且存在冲突的名称。
HRESULT_FROM_WIN32 (ERROR_FILE_EXISTS)
通过 pExtendedParameters 参数传递的 COPYFILE2_EXTENDED_PARAMETERS 结构的 dwCopyFlags 成员包含 COPY_FILE_FAIL_IF_EXISTS 标志，并且存在冲突的名称。

注解

此函数保留扩展属性、OLE 结构化存储、NTFS 文件系统备用数据流和文件属性。 现有文件的安全属性不会复制到新文件。 若要复制安全属性，请使用 SHFileOperation 函数。

如果目标文件已存在并且设置了 FILE_ATTRIBUTE_HIDDEN 或 FILE_ATTRIBUTE_READONLY 属性，则此函数失败HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED)。

若要编译使用此函数的应用程序，请将 _WIN32_WINNT 宏定义为 _WIN32_WINNT_WIN8 或更高版本。 有关详细信息，请参阅 使用 Windows 标头。

在 Windows 8 和 Windows Server 2012 中，此函数由以下技术支持。

技术 支持
服务器消息块 (SMB) 3.0 协议 是
SMB 3.0 透明故障转移 (TFO) 是
具有横向扩展文件共享的 SMB 3.0 (SO) 是
群集共享卷文件系统 (CSV) 是
弹性文件系统 (ReFS) 是

从 Windows 10 版本 1903 和 Windows Server 2022 开始，COPYFILE2_EXTENDED_PARAMETERS 结构中的pExtendedParameters 参数传递给此函数的 dwCopyFlags 字段支持新值COPY_FILE_REQUEST_COMPRESSED_TRAFFIC。 此新值请求基础传输通道在复制操作期间压缩数据。 并非所有媒体都支持请求，在这种情况下，它将被忽略。 压缩属性和参数 (计算复杂性、内存使用情况) 无法通过此 API 进行配置，并且可能会在不同的 OS 版本之间发生更改。 在Windows 10，驻留在 SMB 共享上的文件支持标志，其中协商的 SMB 协议版本为 SMB v3.1.1 或更高版本。

要求

   
最低受支持的客户端 Windows 8 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows Server 2012 [桌面应用 |UWP 应用]
目标平台 Windows
标头 winbase.h (包括 Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

COPYFILE2_EXTENDED_PARAMETERS

文件管理函数