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。失败前已成功复制的文件会保留在目标位置——增量复制行为可确保在重试时仅重新传输未完成或缺失的文件。没有超时;复制会一直进行,直到完成、发生错误或被取消。
