> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WdRemoteCopy

> WdRemoteCopy

# WdRemoteCopy

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

## 语法

```cpp theme={null}
HRESULT WdRemoteCopy(  
         _In_z_ const char* remoteDevice,  
         _In_z_ const char* sourcePath,  
         _In_z_ const char* destinationPath,  
         _In_opt_ const WdCopyOptions* copyOptions,  
         _In_opt_ const WdCopySearchOptions* searchOptions,  
         _In_opt_ const WdCopyStatusCallbacks* statusCallbacks,  
         _In_opt_ WdCancellationHandle cancellationHandle  
);  
```

### 参数

`_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](/reference/remoting/structs/wdcopyoptions)\***

可选。指定复制方向和公共根别名。传入 `nullptr` 以使用默认设置（`CopyTo`；如果 `destinationPath` 是相对路径，则使用默认公共根位置）。

`_In_opt_ searchOptions`\
类型：**const [WdCopySearchOptions](/reference/remoting/structs/wdcopysearchoptions)\***

可选。指定文件的包含/排除模式和属性筛选器（例如 `"*.exe;*.dll"` 表示只复制可执行文件）。传入 `nullptr` 以复制所有文件。

`_In_opt_ statusCallbacks`\
类型：**const [WdCopyStatusCallbacks](/reference/remoting/structs/wdcopystatuscallbacks)\***

可选。指定用于在复制操作期间接收进度更新和诊断消息的回调函数。传入 `nullptr` 以不接收任何回调。

`_In_opt_ cancellationHandle`\
类型：**[WdCancellationHandle](/reference/remoting/structs/wdcancellationhandle)**

可选。由 [WdCreateCancellationHandle](/reference/remoting/functions/wdcreatecancellationhandle) 创建的取消句柄，可从单独的线程传递给 [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy) 以取消复制操作。如果不需要取消功能，则传入 `nullptr`。

### 返回值

类型：**HRESULT**

如果成功，则返回 `S_OK`；否则，返回错误代码。

#### 错误代码

| 代码                      | 值          | 说明                | 根本原因                                              | 故障排除                                                             |
| ----------------------- | ---------- | ----------------- | ------------------------------------------------- | ---------------------------------------------------------------- |
| E\_CONNECTIONERROR      | 0x8C114014 | 连接错误。             | 建立网络连接时的通用故障（传输层故障），与 IP 地址有效性或远程计算机名称解析无关        | 检查远程计算机上的网络连接、防火墙规则和服务可用性；检查设备之间的可见性，两者应能够互相 ping 通；启用日志记录后重试连接。 |
| E\_NAMERESOLUTIONFAILED | 0x8C114012 | 无法解析远程计算机名称。      | 无法通过 DNS 或本地名称解析来解析主机名。                           | 验证主机名拼写、DNS 配置和网络连接。；使用 IP 地址以隔离名称解析问题。                          |
| E\_INVALIDADDRESS       | 0x8C114013 | 无效地址。             | 提供的网络地址不正确、格式错误或不受支持（例如 IP 格式错误、错误的 IP 或不受支持的协议）。 | 确认正确的 IP 地址；更正地址格式并确保使用 IPv4 协议                                  |
| E\_CLIENTNOTAUTHORIZED  | 0x8C114008 | 设备拒绝了客户端。         | 客户端不在该设备的受信任客户端列表中。在完成配对流程之前就尝试了连接                | 成功完成 PIN 码配对流程；重新执行连接请求                                          |
| E\_SERVERNOTAUTHORIZED  | 0x8C114009 | 客户端拒绝了设备。         | 目标设备不在该客户端的受信任端点列表中。在完成配对流程之前就尝试了连接               | 成功完成 PIN 码配对流程；重新执行连接请求                                          |
| E\_SERVERTOOOLD         | 0x8C114011 | 该服务器的版本对此客户端而言过旧。 | 客户端的 API 版本比远程设备上的端点版本更新                          | 将远程计算机上的 wdEndpoint 更新到兼容版本                                      |
| E\_ADMIN\_REQUIRED      | 0x8C114016 | 需要管理员权限。          | 端点未以提升的权限运行，而该操作需要管理员级别的权限                        | 以管理员身份重新运行该端点                                                    |

## 备注

`WdRemoteCopy` 是一个同步的阻塞调用。在所有文件都被复制完成、操作通过 [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy) 被取消或发生错误之前，它不会返回。

要启用取消功能，在调用 `WdRemoteCopy` 之前使用 [WdCreateCancellationHandle](/reference/remoting/functions/wdcreatecancellationhandle) 创建一个 [WdCancellationHandle](/reference/remoting/structs/wdcancellationhandle)，然后从单独的线程将其传递给 [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy)。在 `WdRemoteCopy` 返回后，使用 [WdCloseCancellationHandle](/reference/remoting/functions/wdclosecancellationhandle) 关闭该句柄。

该函数将支持双向复制，但 CopyFrom 当前尚未实现，如果使用将返回 E\_NOTIMPL。使用 [WdCopyDirection::CopyTo](/reference/remoting/enums/wdcopydirection) 将文件从本地 PC 推送到远程设备。默认方向是 `CopyTo`。

如果 `destinationPath` 是绝对路径，则会忽略 [WdCopyOptions](/reference/remoting/structs/wdcopyoptions) 中的 `commonRootAlias`。如果 `destinationPath` 是相对路径，则使用默认公共根位置，除非指定了 `commonRootAlias`。

若要在复制期间接收进度更新，请提供一个带有回调函数指针的 [WdCopyStatusCallbacks](/reference/remoting/structs/wdcopystatuscallbacks) 结构体。

<Info>无论目标设备或目标路径如何，同一时间只能有一个 `WdRemoteCopy` 调用处于活动状态。如果在另一个复制正在进行时调用 `WdRemoteCopy`，将导致未定义的行为。</Info>

`WdRemoteCopy` 在失败时不会自动重试。如果操作因网络中断而失败，调用方必须重新调用 `WdRemoteCopy`。失败前已成功复制的文件会保留在目标位置——增量复制行为可确保在重试时仅重新传输未完成或缺失的文件。没有超时；复制会一直进行，直到完成、发生错误或被取消。

## 示例

### 示例 1：基本文件复制

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

```cpp theme={null}
// BasicCopy.cpp
// Copies a local build folder to a remote device.
// Build: Link against wdremoteapi.lib

#include <windows.h>
#include <stdio.h>
#include "WdRemoteIteration.h"

int main()
{
    // TODO: Replace with your remote device IP address or hostname
    const char* remoteDevice = "192.168.1.100";

    // TODO: Replace with the path to your local build output
    const char* sourcePath = "C:\\builds\\MyGame";

    // TODO: Replace with the desired folder name on the remote device.
    // Relative paths resolve against the default common root.
    const char* destinationPath = "MyGame";

    HRESULT hr = WdRemoteCopy(
        remoteDevice,
        sourcePath,
        destinationPath,
        nullptr,    // copyOptions — defaults to CopyTo direction, default common root
        nullptr,    // searchOptions — copies all files
        nullptr,    // statusCallbacks — no progress reporting
        nullptr);   // cancellationHandle — no cancellation support

    if (SUCCEEDED(hr))
    {
        printf("Copy completed successfully.\n");
    }
    else
    {
        printf("Copy failed: HRESULT 0x%08X\n", hr);
    }

    return hr;
}
```

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

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

```cpp theme={null}
// FilteredCopyWithProgress.cpp
// Copies selected file types with live progress output.
// Build: Link against wdremoteapi.lib

#include <windows.h>
#include <stdio.h>
#include "WdRemoteIteration.h"

HRESULT OnProgress(
    size_t fileProgressCount,
    const WdCopyFileProgressInfo* fileUpdates,
    const WdCopyOperationSummary* summary,
    void* context)
{
    if (summary->totalByteCount > 0)
    {
        double pct = (double)summary->bytesTransferredCount
                   / summary->totalByteCount * 100.0;
        printf("\rProgress: %.1f%% (%llu/%llu files)",
               pct, summary->filesCompletedCount, summary->totalFileCount);
    }
    return S_OK;  // Return S_OK to continue; a failure code aborts the copy
}

int main()
{
    const char* remoteDevice = "192.168.1.100";
    const char* sourcePath   = "C:\\builds\\MyGame";
    const char* destPath     = "MyGame";

    // Only copy executables and data; skip debug symbols and temp files
    WdCopySearchOptions searchOptions = {};
    searchOptions.includeFilePattern   = "*.exe;*.dll;*.ini;*.pak";
    searchOptions.excludeFilePattern   = "*.pdb;*.log;*.tmp";
    searchOptions.excludeDirPattern    = ".vs;obj;Temp;Intermediate";
    searchOptions.includeFileAttributes = 0;  // No attribute-based include filter
    searchOptions.excludeFileAttributes = 0;  // No attribute-based exclude filter

    // Receive progress updates every 500 ms
    WdCopyStatusCallbacks callbacks = {};
    callbacks.copyFilesStatusCallback = OnProgress;
    callbacks.refreshRateMs           = 500;
    callbacks.copyErrorCallback       = nullptr;
    callbacks.context                 = nullptr;

    HRESULT hr = WdRemoteCopy(
        remoteDevice,
        sourcePath,
        destPath,
        nullptr,          // copyOptions — defaults
        &searchOptions,
        &callbacks,
        nullptr);         // cancellationHandle — no cancellation support

    printf("\n");  // Newline after carriage-return progress output

    if (SUCCEEDED(hr))
    {
        printf("Copy completed successfully.\n");
    }
    else
    {
        printf("Copy failed: HRESULT 0x%08X\n", hr);
    }

    return hr;
}
```

## 要求

| 要求          | 值                   |
| ----------- | ------------------- |
| **头文件**     | WdRemoteIteration.h |
| **库**       | wdremoteapi.lib     |
| **支持的操作系统** | Windows 11 及更高版本    |
| **支持的体系结构** | x64、ARM64           |

## 另请参阅

* [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy)
* [WdCancellationHandle](/reference/remoting/structs/wdcancellationhandle)
* [WdCreateCancellationHandle](/reference/remoting/functions/wdcreatecancellationhandle)
* [WdCloseCancellationHandle](/reference/remoting/functions/wdclosecancellationhandle)
* [WdCopyOptions](/reference/remoting/structs/wdcopyoptions)
* [WdCopySearchOptions](/reference/remoting/structs/wdcopysearchoptions)
* [WdCopyStatusCallbacks](/reference/remoting/structs/wdcopystatuscallbacks)
* [WdCopyDirection](/reference/remoting/enums/wdcopydirection)
* [XBOX PC 远程迭代 API 错误代码](/reference/remoting/error-codes)
* [XBOX PC 远程迭代 API](/reference/remoting/remoteiteration_members)


## Related topics

- [WdCancelRemoteCopy](/zh-CN/reference/remoting/functions/wdcancelremotecopy.md)
- [WdCopyDirection](/zh-CN/reference/remoting/enums/wdcopydirection.md)
- [WdCopyOptions](/zh-CN/reference/remoting/structs/wdcopyoptions.md)
- [WdCopyFilesStatusCallback](/zh-CN/reference/remoting/callbacks/wdcopyfilesstatuscallback.md)
- [WdCopyErrorCallback](/zh-CN/reference/remoting/callbacks/wdcopyerrorcallback.md)