Skip to main content

WdRemoteCopy

在本地 PC 与远程设备之间复制文件。

语法

参数

_In_z_ remoteDevice
类型:const char*
远程设备的主机名或 IP 地址(例如 "192.168.1.100""MyDevKit")。 _In_z_ sourcePath
类型:const char*
要复制的源路径(例如复制到远程设备时的 "C:\\builds\\MyGame")。 _In_z_ destinationPath
类型:const char*
复制到的目标路径。可以是绝对路径(例如 "D:\\Games\\MyGame"),或相对于公共根解析的相对路径(例如 "MyGame")。 _In_opt_ copyOptions
类型:const WdCopyOptions*
可选。指定复制方向和公共根别名。传入 nullptr 以使用默认设置(CopyTo;如果 destinationPath 是相对路径,则使用默认公共根位置)。 _In_opt_ searchOptions
类型:const WdCopySearchOptions*
可选。指定文件的包含/排除模式和属性筛选器(例如 "*.exe;*.dll" 表示只复制可执行文件)。传入 nullptr 以复制所有文件。 _In_opt_ statusCallbacks
类型:const WdCopyStatusCallbacks*
可选。指定用于在复制操作期间接收进度更新和诊断消息的回调函数。传入 nullptr 以不接收任何回调。 _In_opt_ cancellationHandle
类型:WdCancellationHandle
可选。由 WdCreateCancellationHandle 创建的取消句柄,可从单独的线程传递给 WdCancelRemoteCopy 以取消复制操作。如果不需要取消功能,则传入 nullptr

返回值

类型:HRESULT 如果成功,则返回 S_OK;否则,返回错误代码。

错误代码

备注

WdRemoteCopy 是一个同步的阻塞调用。在所有文件都被复制完成、操作通过 WdCancelRemoteCopy 被取消或发生错误之前,它不会返回。 要启用取消功能,在调用 WdRemoteCopy 之前使用 WdCreateCancellationHandle 创建一个 WdCancellationHandle,然后从单独的线程将其传递给 WdCancelRemoteCopy。在 WdRemoteCopy 返回后,使用 WdCloseCancellationHandle 关闭该句柄。 该函数将支持双向复制,但 CopyFrom 当前尚未实现,如果使用将返回 E_NOTIMPL。使用 WdCopyDirection::CopyTo 将文件从本地 PC 推送到远程设备。默认方向是 CopyTo 如果 destinationPath 是绝对路径,则会忽略 WdCopyOptions 中的 commonRootAlias。如果 destinationPath 是相对路径,则使用默认公共根位置,除非指定了 commonRootAlias 若要在复制期间接收进度更新,请提供一个带有回调函数指针的 WdCopyStatusCallbacks 结构体。
无论目标设备或目标路径如何,同一时间只能有一个 WdRemoteCopy 调用处于活动状态。如果在另一个复制正在进行时调用 WdRemoteCopy,将导致未定义的行为。
WdRemoteCopy 在失败时不会自动重试。如果操作因网络中断而失败,调用方必须重新调用 WdRemoteCopy。失败前已成功复制的文件会保留在目标位置——增量复制行为可确保在重试时仅重新传输未完成或缺失的文件。没有超时;复制会一直进行,直到完成、发生错误或被取消。

示例

示例 1:基本文件复制

使用默认设置将本地生成文件夹复制到远程设备。所有文件都被复制,没有筛选、进度报告或取消支持。

示例 2:带进度报告的筛选复制

仅复制特定文件类型,同时跳过调试构件和中间目录。进度回调将实时传输状态打印到控制台。

要求

另请参阅

最后修改于 2026年8月24日