> ## 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 與遠端裝置之間複製檔案。

**推出版本：** [RIT 0.0.8-Preview](/zh-TW/reference/remoting/release-versions#release-versions)。

**`CopyFrom` 支援起始版本：** [RIT 0.0.13-preview](/zh-TW/reference/remoting/release-versions#release-versions)。請參閱[變更歷程記錄](#change-history)。

## 語法

```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"`)。對於 `CopyTo`，這是本機路徑；對於 `CopyFrom`，這是遠端路徑。

`_In_z_ destinationPath`\
類型：**const char\***

要複製到的目的地路徑。對於 `CopyTo`，這是遠端路徑，可以是絕對路徑 (例如 `"D:\\Games\\MyGame"`) 或相對於通用根目錄的路徑 (例如 `"MyGame"`)。對於 `CopyFrom`，這是本機路徑。

`_In_opt_ copyOptions`\
類型：**const [WdCopyOptions](/zh-TW/reference/remoting/structs/wdcopyoptions)\***

選用。指定複製方向與通用根目錄別名。傳遞 `nullptr` 以使用預設設定 (`CopyTo`，若 `destinationPath` 是相對路徑則使用預設通用根目錄位置)。

`_In_opt_ searchOptions`\
類型：**const [WdCopySearchOptions](/zh-TW/reference/remoting/structs/wdcopysearchoptions)\***

選用。指定檔案包含/排除模式和屬性篩選條件 (例如在 `CopyTo` 中使用 `"*.exe;*.dll"` 只複製可執行檔)。對於 `CopyFrom`，名稱模式不會限制遠端檔案的選取。傳遞 `nullptr` 以複製所有檔案。

`_In_opt_ statusCallbacks`\
類型：**const [WdCopyStatusCallbacks](/zh-TW/reference/remoting/structs/wdcopystatuscallbacks)\***

選用。指定在複製作業期間接收進度更新和診斷訊息的回呼函式。傳遞 `nullptr` 則不接收任何回呼。

`_In_opt_ cancellationHandle`\
類型：**[WdCancellationHandle](/zh-TW/reference/remoting/structs/wdcancellationhandle)**

選用。由 [WdCreateCancellationHandle](/zh-TW/reference/remoting/functions/wdcreatecancellationhandle) 建立的取消控制代碼，可從另一個執行緒傳遞給 [WdCancelRemoteCopy](/zh-TW/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](/zh-TW/reference/remoting/functions/wdcancelremotecopy) 取消，或發生錯誤之前，它都不會傳回。

若要啟用取消功能，請在呼叫 `WdRemoteCopy` 之前使用 [WdCreateCancellationHandle](/zh-TW/reference/remoting/functions/wdcreatecancellationhandle) 建立 [WdCancellationHandle](/zh-TW/reference/remoting/structs/wdcancellationhandle)，然後從另一個執行緒將它傳遞給 [WdCancelRemoteCopy](/zh-TW/reference/remoting/functions/wdcancelremotecopy)。`WdRemoteCopy` 傳回之後，請使用 [WdCloseCancellationHandle](/zh-TW/reference/remoting/functions/wdclosecancellationhandle) 關閉控制代碼。

使用 [WdCopyDirection::CopyTo](/zh-TW/reference/remoting/enums/wdcopydirection) 將檔案從本機 PC 推送到遠端裝置，或使用 `CopyFrom` 將檔案從遠端裝置提取到本機 PC。預設方向為 `CopyTo`。

對於 `CopyTo`，遠端路徑是 `destinationPath`；對於 `CopyFrom`，遠端路徑是 `sourcePath`。如果該路徑是絕對路徑，則會忽略 [WdCopyOptions](/zh-TW/reference/remoting/structs/wdcopyoptions) 中的 `commonRootAlias`。如果是相對路徑，除非指定了 `commonRootAlias`，否則會使用預設的通用根目錄位置。

若要在複製期間接收進度更新，請提供含有回呼函式指標的 [WdCopyStatusCallbacks](/zh-TW/reference/remoting/structs/wdcopystatuscallbacks) 結構。

<Warning>無論目標裝置或目的地路徑為何，一次只能有一個 `WdRemoteCopy` 呼叫處於作用中狀態。在另一個複製作業進行中時呼叫 `WdRemoteCopy`，會導致未定義的行為。  </Warning>
`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;  // A failed callback HRESULT is logged, but does not abort 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

    // Request a 500 ms progress update interval
    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;
}
```

## 變更歷程記錄

| 版本 | 變更 |
| - | - |
| [RIT 0.0.13-preview](/zh-TW/reference/remoting/release-versions#release-versions) | 實作 `CopyFrom`。較早的版本對此方向會傳回 `E_NOTIMPL`，即使已宣告該列舉值。 |
| [RIT 0.0.8-Preview](/zh-TW/reference/remoting/release-versions#release-versions) | 推出支援 `CopyTo` 的 `WdRemoteCopy`。 |

## 需求

| 需求 | 值 |
| - | - |
| **標頭** | WdRemoteIteration.h |
| **程式庫** | wdremoteapi.lib |
| **支援的作業系統** | Windows 11 及更新版本 |
| **支援的架構** | x64, ARM64 |

## 另請參閱

* [WdCancelRemoteCopy](/zh-TW/reference/remoting/functions/wdcancelremotecopy)
* [WdCancellationHandle](/zh-TW/reference/remoting/structs/wdcancellationhandle)
* [WdCreateCancellationHandle](/zh-TW/reference/remoting/functions/wdcreatecancellationhandle)
* [WdCloseCancellationHandle](/zh-TW/reference/remoting/functions/wdclosecancellationhandle)
* [WdCopyOptions](/zh-TW/reference/remoting/structs/wdcopyoptions)
* [WdCopySearchOptions](/zh-TW/reference/remoting/structs/wdcopysearchoptions)
* [WdCopyStatusCallbacks](/zh-TW/reference/remoting/structs/wdcopystatuscallbacks)
* [WdCopyDirection](/zh-TW/reference/remoting/enums/wdcopydirection)
* [XBOX PC Remote Iteration API 錯誤碼](/zh-TW/reference/remoting/error-codes)
* [XBOX PC Remote Iteration API](/zh-TW/reference/remoting/remoteiteration_members)


## Related topics

- [WdRemoteCopy](/reference/remoting/functions/wdremotecopy.md)
- [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy.md)
- [WdCopyDirection](/reference/remoting/enums/wdcopydirection.md)
- [WdCopyOptions](/reference/remoting/structs/wdcopyoptions.md)
- [WdCopyErrorCallback](/reference/remoting/callbacks/wdcopyerrorcallback.md)