> ## 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`\
Type: **const char\***

リモート デバイスのホスト名または IP アドレス (例: `"192.168.1.100"` または `"MyDevKit"`)。

`_In_z_ sourcePath`\
Type: **const char\***

コピー元のソース パス (例: リモート デバイスにコピーする場合、`"C:\\builds\\MyGame"`)。

`_In_z_ destinationPath`\
Type: **const char\***

コピー先の宛先パス。絶対パス (例: `"D:\\Games\\MyGame"`)、または共通ルートに対して解決される相対パス (例: `"MyGame"`) を指定できます。

`_In_opt_ copyOptions`\
Type: **const [WdCopyOptions](/reference/remoting/structs/wdcopyoptions)\***

省略可能。コピーの方向および共通ルート エイリアスを指定します。既定の設定 (`CopyTo`、`destinationPath` が相対パスの場合の既定の共通ルート場所) を使用するには `nullptr` を渡します。

`_In_opt_ searchOptions`\
Type: **const [WdCopySearchOptions](/reference/remoting/structs/wdcopysearchoptions)\***

省略可能。ファイルの包含/除外パターンと属性フィルターを指定します (例: 実行可能ファイルのみをコピーする場合は `"*.exe;*.dll"`)。すべてのファイルをコピーするには `nullptr` を渡します。

`_In_opt_ statusCallbacks`\
Type: **const [WdCopyStatusCallbacks](/reference/remoting/structs/wdcopystatuscallbacks)\***

省略可能。コピー操作中に進捗更新および診断メッセージを受け取るためのコールバック関数を指定します。コールバックを受け取らないようにするには `nullptr` を渡します。

`_In_opt_ cancellationHandle`\
Type: **[WdCancellationHandle](/reference/remoting/structs/wdcancellationhandle)**

省略可能。[WdCreateCancellationHandle](/reference/remoting/functions/wdcreatecancellationhandle) で作成されたキャンセル ハンドル。別のスレッドから [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy) に渡して、コピー操作をキャンセルできます。キャンセルが不要な場合は `nullptr` を渡します。

### 戻り値

Type: **HRESULT**

成功した場合は `S_OK` を返します。それ以外の場合はエラー コードを返します。

#### エラー コード

| コード                     | 値          | 説明                          | 根本原因                                                                                     | トラブルシューティング                                                                                                        |
| ----------------------- | ---------- | --------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| E\_CONNECTIONERROR      | 0x8C114014 | 接続エラー。                      | IP アドレスの有効性やリモート マシン名の解決とは無関係の、ネットワーク接続の確立時の一般的な失敗 (トランスポート レベルの失敗)                      | ネットワーク接続、ファイアウォールの規則、リモート マシン上のサービスの可用性を確認してください。デバイス間の可視性を確認してください。デバイスは互いに ping できる必要があります。ログを有効にして接続を再試行してください。 |
| E\_NAMERESOLUTIONFAILED | 0x8C114012 | リモート マシン名を解決できませんでした。       | DNS またはローカル名前解決を介してホスト名を解決できません。                                                         | ホスト名のスペル、DNS 構成、ネットワーク接続を確認してください。IP アドレスを使用して名前解決の問題を切り分けてください。                                                   |
| E\_INVALIDADDRESS       | 0x8C114013 | 無効なアドレス。                    | 正しくない、不正な形式の、またはサポートされていないネットワーク アドレスが指定されました (例: 不正な IP 形式、間違った IP、またはサポートされていないプロトコル)。 | 正しい IP アドレスを確認してください。アドレスの形式を修正し、IPv4 プロトコルを使用していることを確認してください                                                      |
| E\_CLIENTNOTAUTHORIZED  | 0x8C114008 | デバイスがクライアントを拒否しました。         | クライアントがデバイスの信頼できるクライアントのリストにありません。ペアリング プロセスを完了する前に接続試行が開始されました                          | ピン ペアリング プロセスを正常に完了してください。接続要求を再度実行してください                                                                          |
| E\_SERVERNOTAUTHORIZED  | 0x8C114009 | クライアントがデバイスを拒否しました。         | ターゲット デバイスがクライアントの信頼できるエンドポイントのリストにありません。ペアリング プロセスを完了する前に接続試行が開始されました                   | ピン ペアリング プロセスを正常に完了してください。接続要求を再度実行してください                                                                          |
| 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` の呼び出しは同時に 1 つだけアクティブにできます。別のコピーが既に進行中の状態で `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     |
| **サポートされている OS**     | 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 Remote Iteration API エラー コード](/reference/remoting/error-codes)
* [XBOX PC Remote Iteration API](/reference/remoting/remoteiteration_members)


## Related topics

- [WdCancelRemoteCopy](/ja-jp/reference/remoting/functions/wdcancelremotecopy.md)
- [WdCopyOptions](/ja-jp/reference/remoting/structs/wdcopyoptions.md)
- [WdCopyDirection](/ja-jp/reference/remoting/enums/wdcopydirection.md)
- [WdCopyErrorCallback](/ja-jp/reference/remoting/callbacks/wdcopyerrorcallback.md)
- [WdCopyErrorSeverity](/ja-jp/reference/remoting/enums/wdcopyerrorseverity.md)