> ## 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.

# XBOX PC Remote Iteration API

> XBOX PC Remote Iteration API リファレンス: リモートの Windows ベース開発デバイスでファイルのコピー、ゲームの起動、再開、および終了を行う関数を提供します。

# XBOX PC Remote Iteration API

リモートの Windows ベース デバイスに対して、ファイルのコピー、ゲームの起動、再開、および終了を行う関数を提供します。

<Note>
  アプリ ベースのワークフローをお探しですか？ XBOX PC Toolbox アプリ、`wdRemote` と `wdEndpoint` のコマンドライン ツール、および Visual Studio リモート デバッガーについては、[XBOX PC Remote Tools](/tools/tools-pc/xbox-pc-remote-tools) のチュートリアルを参照してください。
</Note>

## はじめに

<CardGroup cols={2}>
  <Card title="XBOX PC Remote Tools の概要" icon="network-wired" href="/tools/tools-pc/xbox-pc-remote-tools">
    リモート Windows デバイスでのプロビジョニング、デプロイ、起動、デバッグ、イテレーションを行います。
  </Card>

  <Card title="クイックスタート" icon="rocket" href="/tools/tools-pc/xbox-pc-remote-tools/quickstart">
    XBOX PC Toolbox アプリをインストールして、開発デバイスとターゲット デバイスをペアリングします。
  </Card>

  <Card title="wdRemote コマンドライン ツール" icon="terminal" href="/tools/tools-pc/commandlinetools/gr-wdRemote">
    リモート イテレーション ワークフローをコマンドラインで制御します。
  </Card>

  <Card title="FAQ とトラブルシューティング" icon="circle-question" href="/tools/tools-pc/xbox-pc-remote-tools/faq">
    よくある質問、既知の問題、および修正方法。
  </Card>
</CardGroup>

## 概要

XBOX PC Remote Iteration API は、リモートの Windows デバイスを対象とする PC ベースの開発ワークフローを可能にします。ローカル PC とリモート デバイス間でのゲーム ファイル転送、リモート デバイス上でのゲーム プロセスの起動と管理、およびリモート実行のためのゲーム登録を行う C 関数のセットを提供します。この API は、ゲーム開発中の緊密なイテレーション ループのために設計されており、開発者はローカルでビルドし、手動でファイル管理を行うことなくリモート ハードウェアでデプロイおよびテストできます。

## 使用する場面

* 開発中に、ローカル PC からリモート Windows デバイスへゲーム ビルドをデプロイする場合。
* イテレーティブ ビルド中の転送時間を最小化するために、更新されたファイル (差分コピー) をリモート デバイスにコピーする場合。
* 開発 PC からリモート デバイス上のゲーム プロセスを起動、中断、再開、終了する場合。
* リモート Windows デバイスを対象とした継続的インテグレーション パイプラインでビルド、デプロイ、テストのワークフローを自動化する場合。
* リモート Windows デバイスへのローカルまたはテスト ラボでのデプロイを行うカスタム スタジオ ツールを構築または統合する場合。

## 使用すべきでない場面

* この API は、リテール ゲームやエンドユーザー コンソールへの本番デプロイには使用しないでください。
* この API は、2 台のリモート デバイス間のファイル転送には使用しないでください。エンドポイントの一方はローカル PC である必要があります。
* リモート デバイスがペアリングされておらず、リモート開発用に構成されていない場合は、この API を使用しないでください。

## 前提条件

* **NuGet パッケージ:** [Microsoft.GDK.RemoteIterationClientApi](https://aka.ms/GameDevRemoteAPI) バージョン 0.1.0-preview\.26.3.6001 以降。
* **デバイスのペアリング:** [XBOX PC Toolbox](/tools/tools-pc/xboxpctoolbox/xboxpctoolbox) アプリを使用してプロビジョニングし、ローカル PC とリモート デバイスをペアリングして相互に信頼させる必要があります。
* **wdEndpoint:** リモート デバイスに `wdEndpoint` がインストールされ、実行されている必要があります。[XBOX PC Toolbox](/tools/tools-pc/xboxpctoolbox/xboxpctoolbox) のセットアップでは、既定で `wdEndpoint` がインストールおよび構成されます。
* **ヘッダーとライブラリ:** `WdRemoteIteration.h` をインクルードし、`wdremoteapi.lib` をリンクします。

## 関数

| 関数                                                                                           | 説明                                      |
| -------------------------------------------------------------------------------------------- | --------------------------------------- |
| [WdRemoteCopy](/reference/remoting/functions/wdremotecopy)                                   | ローカル PC とリモート デバイス間でファイルをコピーします。        |
| [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy)                       | 進行中のコピー操作をキャンセルします。                     |
| [WdCreateCancellationHandle](/reference/remoting/functions/wdcreatecancellationhandle)       | コピー操作をキャンセルするためのキャンセル ハンドルを作成します。       |
| [WdCloseCancellationHandle](/reference/remoting/functions/wdclosecancellationhandle)         | キャンセル ハンドルを閉じます。                        |
| [WdDuplicateCancellationHandle](/reference/remoting/functions/wdduplicatecancellationhandle) | 既存のキャンセル ハンドルを複製します。                    |
| [WdLaunchRemoteGame](/reference/remoting/functions/wdlaunchremotegame)                       | リモート デバイス上でゲームを起動します。                   |
| [WdResumeRemoteGame](/reference/remoting/functions/wdresumeremotegame)                       | リモート デバイス上でサスペンド モードで最後に起動されたゲームを再開します。 |
| [WdTerminateRemoteGame](/reference/remoting/functions/wdterminateremotegame)                 | リモート デバイス上で最後に起動されたゲームを終了します。           |
| [WdRegisterRemoteXboxGame](/reference/remoting/functions/wdregisterremotexboxgame)           | リモート デバイスにゲームを登録します。                    |

## 構造体

| 構造体                                                                          | 説明                                         |
| ---------------------------------------------------------------------------- | ------------------------------------------ |
| [WdCopyFileProgressInfo](/reference/remoting/structs/wdcopyfileprogressinfo) | コピー操作中の個別ファイルの進捗情報を格納します。                  |
| [WdCopyOperationSummary](/reference/remoting/structs/wdcopyoperationsummary) | コピー操作全体のサマリー進捗情報を格納します。                    |
| [WdCopyOptions](/reference/remoting/structs/wdcopyoptions)                   | コピー操作の方向とモードを指定します。                        |
| [WdCopyStatusCallbacks](/reference/remoting/structs/wdcopystatuscallbacks)   | コピー ステータス更新を受け取るためのコールバック関数ポインターと設定を格納します。 |
| [WdCopySearchOptions](/reference/remoting/structs/wdcopysearchoptions)       | コピー操作のファイルおよびディレクトリのフィルター パターンを指定します。      |
| [WdCancellationHandle](/reference/remoting/structs/wdcancellationhandle)     | 進行中のコピー操作をキャンセルするために使用される不透明ハンドル。          |
| [WdLaunchOptions](/reference/remoting/structs/wdlaunchoptions)               | リモート デバイス上でゲームを起動するためのオプションを指定します。         |

## 列挙型

| 列挙型                                                                  | 説明                           |
| -------------------------------------------------------------------- | ---------------------------- |
| [WdCopyDirection](/reference/remoting/enums/wdcopydirection)         | コピー操作の方向を指定します。              |
| [WdLaunchMode](/reference/remoting/enums/wdlaunchmode)               | リモート ゲームの起動モードを指定します。        |
| [WdCopyErrorSeverity](/reference/remoting/enums/wdcopyerrorseverity) | コピー エラーまたは警告メッセージの重大度を指定します。 |

## コールバック

| コールバック                                                                               | 説明                                   |
| ------------------------------------------------------------------------------------ | ------------------------------------ |
| [WdCopyFilesStatusCallback](/reference/remoting/callbacks/wdcopyfilesstatuscallback) | コピー操作中にファイル コピーの進捗を報告するために呼び出されます。   |
| [WdCopyErrorCallback](/reference/remoting/callbacks/wdcopyerrorcallback)             | コピー操作中にエラーおよび警告メッセージを報告するために呼び出されます。 |

## スレッド モデル

XBOX PC Remote Iteration API は、シングルスレッドのコピー操作向けに設計されています。次の規則が適用されます。

* **同時に 1 つのコピーのみ。** ターゲット デバイスやコピー先のパスに関係なく、任意の時点でアクティブにできる [WdRemoteCopy](/reference/remoting/functions/wdremotecopy) の呼び出しは 1 つだけです。別のコピーがすでに進行中に `WdRemoteCopy` を呼び出すと、**動作は未定義** となります。
* **コピー中に他の関数を呼び出すのは安全です。** [WdLaunchRemoteGame](/reference/remoting/functions/wdlaunchremotegame)、[WdTerminateRemoteGame](/reference/remoting/functions/wdterminateremotegame)、[WdResumeRemoteGame](/reference/remoting/functions/wdresumeremotegame)、[WdRegisterRemoteXboxGame](/reference/remoting/functions/wdregisterremotexboxgame) などの関数は、コピー中に別のスレッドから呼び出すことができます。
* **すべての関数はブロッキングです。** API のすべての関数は、操作が完了または失敗するまで呼び出し元のスレッドをブロックします。特に `WdRemoteCopy` は、転送サイズやネットワーク状況によって長時間ブロックする可能性があります。
* **キャンセルはスレッド セーフです。** [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy) は任意のスレッドから呼び出すことができます。複数のスレッドが同じ操作を同時にキャンセルしようとした場合、呼び出しは内部でシリアル化されます — 最初の呼び出しは成功し、それ以降の呼び出しはキャンセルするものが残っていないためエラーを返します。
* **呼び出し間で接続状態は保持されません。** 各 API 呼び出しは、リモート デバイスへの独自の接続を確立します。永続的なセッションはありません — たとえば、[WdLaunchRemoteGame](/reference/remoting/functions/wdlaunchremotegame) の完了後に接続が切断されても、接続が復旧すれば引き続き [WdTerminateRemoteGame](/reference/remoting/functions/wdterminateremotegame) を呼び出すことができます。

## 再試行の動作

XBOX PC Remote Iteration API は、失敗した操作を API レベルで自動的に再試行することは **ありません**。ネットワーク中断やその他の一時的なエラーで操作が失敗した場合、呼び出し元が再試行を行う必要があります。

* **自動再試行なし。** コピー操作が失敗した場合 (たとえば、ネットワーク接続が失われた場合など)、`WdRemoteCopy` はエラーを返します。呼び出し元は再試行のために関数を再度呼び出す必要があります。
* **タイムアウトは構成不可。** `WdRemoteCopy` はコピー操作にタイムアウトを課しません。完了するか、エラーが発生するか、[WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy) 経由でキャンセルされるまで転送を続行します。ネットワーク状況が悪化している場合、転送は失敗するのではなく非常に低速になる可能性があります。
* **失敗時に進捗は保持されます。** 失敗前に正常にコピーされたファイルは、コピー先に残ります。呼び出し元がコピーを再試行すると、差分コピーの動作により、未完了または欠落しているファイルのみが転送されます — 以前にコピーされたファイルは再転送されません。
* **ディスク容量エラーは報告されます。** コピー中に転送先デバイスのディスク容量が不足した場合、操作はハングするのではなくエラーで失敗します。
* **トランスポート レベルの耐性。** 基礎となるトランスポート層は、低レベルのパケット再送を透過的に処理します。軽微なネットワーク障害 (単一パケットのドロップなど) では操作は失敗しません。ただし、接続が長時間失われると最終的にエラーになります。
* **推奨される再試行パターン。** `WdRemoteCopy` の失敗後は、同じパラメーターで `WdRemoteCopy` を単純に再呼び出しします。差分コピーの動作により、転送先で欠落または未完了のファイルのみが転送されるため、冗長な作業が最小化されます。

## キャンセル

XBOX PC Remote Iteration API は、長時間実行されるコピー操作に対して、ハンドル ベースのキャンセル モデルを提供します。ハンドルのライフサイクルは呼び出し元の責任です。

1. [WdCreateCancellationHandle](/reference/remoting/functions/wdcreatecancellationhandle) を呼び出してハンドルを作成します。
2. `cancellationHandle` パラメーター経由でハンドルを [WdRemoteCopy](/reference/remoting/functions/wdremotecopy) に渡します。
3. 別のスレッドから、ハンドルを指定して [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy) を呼び出し、進行中のコピーをキャンセルします。`WdCancelRemoteCopy` はノンブロッキングです。キャンセルがシグナルされた後、`WdRemoteCopy` はキャンセルを完了して `S_OK` を返します。
4. `WdRemoteCopy` が返った後、[WdCloseCancellationHandle](/reference/remoting/functions/wdclosecancellationhandle) を呼び出してハンドルを閉じます。

複数のコンポーネントが同じキャンセル ハンドルを参照する必要がある場合は、[WdDuplicateCancellationHandle](/reference/remoting/functions/wdduplicatecancellationhandle) を使用して複製してください。各コピーは個別にクローズする必要があります。

## 共通ルート

共通ルートは、リモート デバイス上でゲームが通常コピーされたり起動されたりする、事前構成された既知の場所です。呼び出し元は、完全な絶対パスを指定するのではなく、[WdCopyOptions](/reference/remoting/structs/wdcopyoptions) や [WdLaunchOptions](/reference/remoting/structs/wdlaunchoptions) の `commonRootAlias` フィールドを使用してエイリアスでこれらの場所を参照できます。

`destinationPath` が絶対パスの場合、`commonRootAlias` は無視されます。`destinationPath` が相対パスの場合、エイリアスで識別される共通ルートを基準に解決されます。エイリアスが指定されていない場合は、既定の共通ルートの場所が使用されます。

## エラー コード

API 固有のエラー コードの完全な一覧については、説明、根本原因、およびトラブルシューティング ガイダンスを含めて、[XBOX PC Remote Iteration API エラー コード](/reference/remoting/error-codes) を参照してください。

## バージョン管理、サービシング、および配布

Remote Iteration Tools (RIT) API は、互換性、アップグレード、および長期サポートに関する明確な期待を提供するために、**セマンティック バージョニング 2.0.0** (`MAJOR.MINOR.PATCH`) に準拠しています。すべての RIT API パブリック ライブラリは **NuGet** 経由で配布されるため、標準的な依存関係管理と更新ワークフローが可能です。

### バージョン管理モデル

#### PATCH リリース

`PATCH` 更新はバグ修正と信頼性の向上を提供します。これらの更新は API 契約やランタイム動作を変更 **せず**、安全にドロップイン更新できます。より新しい `PATCH` バージョンに更新してもコード変更は不要です。

#### MINOR リリース

`MINOR` 更新は、後方互換性のある方法で新しい API を導入したり、既存の機能を進化させたりします。将来の変更や削除が予定されている API については、非推奨として明確にマークされ、開発者に移行時間を与えます。依存関係の更新は、同じ `MAJOR` バージョン内で互換性を確保するようにレビューされます。

#### MAJOR リリース

`MAJOR` 更新は、意図的な破壊的変更を表します。これらのリリースはコード変更や依存関係の更新を必要とする場合があり、明確な移行ガイダンスが伴います。新しい `MAJOR` バージョンへのアップグレードは、通常の検証およびリリース サイクルに沿った、明示的でオプトインの決定として扱われます。

### サービシングとサポート モデル

RIT API の `MAJOR` または `MINOR` バージョンが公開リリースされると、およそ **18 か月** の目標サポート ウィンドウでアクティブなサービシング期間に入ります。この期間中:

* サポート対象バージョンに対するバグ修正と信頼性向上のために `PATCH` リリースが承認されます。
* 新しいバージョンがリリースされ、パッチやマイナー変更が既存バージョンの改良やバグ修正を行うと、複数の `MAJOR` および `MINOR` バージョンが同時にサービシングされる場合があります。
* `PATCH` リリースは、`MAJOR` または `MINOR` バージョンのサービシング期間を延長するもので **ありません**。
* 新機能は、より新しい `MINOR` または `MAJOR` リリースでのみ導入され、バックポートされません。

サービシング ウィンドウが終了すると、そのバージョンはリタイヤされ、開発者はサポートされているより新しい `MAJOR` または `MINOR` リリースに移行することが期待されます。

### アップグレードの期待

開発者には、`PATCH` および `MINOR` 更新を取り入れることで、`MAJOR` バージョン内で最新の状態を保つことが推奨されます。`MAJOR` バージョンのアップグレードは、本番ワークフローとの互換性を確保するために、明示的に計画および検証する必要があります。

### API と wdEndpoint のバージョン互換性

RIT API クライアント ライブラリと、リモート デバイス上で動作する `wdEndpoint` は、常に互換性のあるバージョンに保つ必要があります。より新しい API バージョンをより古い `wdEndpoint` と一緒に使用すると、`E_SERVERTOOOLD` エラーや予期しない動作が発生する可能性があります。正しい動作、完全な後方互換性、および最新の API 機能のサポートを保証するために、API クライアント ライブラリを更新するたびに、すべてのリモート デバイス上の `wdEndpoint` を更新することをお勧めします。最小限の `wdEndpoint` バージョン要件については、NuGet パッケージのリリース ノートを参照してください。

## 要件

| 要件                | 値                                                                         |
| ----------------- | ------------------------------------------------------------------------- |
| **ヘッダー**          | WdRemoteIteration.h                                                       |
| **ライブラリ**         | wdremoteapi.lib                                                           |
| **NuGet パッケージ**   | [Microsoft.GDK.RemoteIterationClientApi](https://aka.ms/GameDevRemoteAPI) |
| **サポート対象 OS**     | Windows 11 以降                                                             |
| **サポート対象アーキテクチャ** | x64、ARM64                                                                 |

## 概念ドキュメント

<Card title="XBOX PC Remote Tools" icon="network-wired" href="/tools/tools-pc/xbox-pc-remote-tools">
  リモート Windows デバイスをセットアップし、XBOX PC Remote Tools を使用してデプロイ、起動、デバッグ、イテレーションを行います。
</Card>

* [XBOX PC Remote Tools リリース ノート (2026 年 3 月)](/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603)

## 関連項目

* [WdRemoteCopy](/reference/remoting/functions/wdremotecopy)
* [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy)
* [WdCreateCancellationHandle](/reference/remoting/functions/wdcreatecancellationhandle)
* [WdLaunchRemoteGame](/reference/remoting/functions/wdlaunchremotegame)
* [WdRegisterRemoteXboxGame](/reference/remoting/functions/wdregisterremotexboxgame)


## Related topics

- [XBOX PC Remote Tools: 2026 年 3 月 (2603) リリース ノート](/ja-jp/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603.md)
- [XBOX PC Remote Iteration API エラー コード](/ja-jp/reference/remoting/error-codes.md)
- [XBOX PC Remote Tools](/ja-jp/tools/tools-pc/xbox-pc-remote-tools/index.md)
- [WdRegisterRemoteXboxGame](/ja-jp/reference/remoting/functions/wdregisterremotexboxgame.md)
- [WdTerminateRemoteGame](/ja-jp/reference/remoting/functions/wdterminateremotegame.md)