> ## Documentation Index > Fetch the complete documentation index at: https://docs.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 reference: functions to copy files, launch, resume, and terminate games on remote Windows-based development devices. Provides functions for copying and deleting files, and launching, resuming, and terminating games on remote Windows-based devices. ## Overview The XBOX PC Remote Iteration API enables PC-based development workflows that target remote Windows devices. It provides a set of C functions for transferring game files between a local PC and a remote device, and launching and managing game processes on the remote device. The API is designed for tight iteration loops during game development, allowing developers to build locally and deploy and test on remote hardware without manual file management. ## API availability This reference describes the latest API. Unless a later release is specified, public API declarations are available in [RIT 0.0.8-Preview](https://docs.xbox.com/reference/remoting/release-versions.md#release-versions), the initial public API release. **Introduced in** identifies when a declaration was added. **Supported from** identifies when a declared option became functional. A declaration's introduction does not imply that currently unused callbacks or settings are implemented. **Change history** sections describe changes to API declarations or behavior, not corrections to the documentation. Release labels use the WinGet version. The [release version table](https://docs.xbox.com/reference/remoting/release-versions.md#release-versions) maps each label to the API NuGet package and command-line tool versions. ## When to use * Deploying game builds from a local PC to a remote Windows device during development. * Copying updated files (delta copy) to a remote device to minimize transfer times during iterative builds. * Removing stale build output from a remote device before deploying a new build. * Launching, suspending, resuming, and terminating game processes on a remote device from your development PC. * Automating build-deploy-test workflows in continuous integration pipelines targeting remote Windows devices. * Building or integrating into custom studio tooling for deployment to remote Windows devices locally or in test labs. ## When NOT to use * Do not use this API for retail or production deployment of games to end-user consoles. * Do not use this API to transfer files between two remote devices; one endpoint must be the local PC. * Do not use this API if the remote device has not been paired and configured for remote development. ## Prerequisites * **NuGet Package:** [Microsoft.GDK.RemoteIterationClientApi](https://aka.ms/GameDevRemoteAPI) version 0.1.0-preview\.26.3.6001 or later for the base API. Later APIs and options require the releases identified on their reference pages. * **Device Pairing:** The local PC and the remote device must be paired and mutually trusted by using the [XBOX PC Toolbox](https://docs.xbox.com/tools/tools-pc/xboxpctoolbox/xboxpctoolbox.md) app to provision them. * **wdEndpoint:** `wdEndpoint` must be installed and running on the remote device. The [XBOX PC Toolbox](https://docs.xbox.com/tools/tools-pc/xboxpctoolbox/xboxpctoolbox.md) setup installs and configures `wdEndpoint` by default. * **Header and Library:** Include `WdRemoteIteration.h` and link against `wdremoteapi.lib`. ## Sample The [Remote Iteration Tools Sample](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/Tools/RemoteIterationToolsSample) is a C# WPF application that demonstrates how to deploy, launch, resume, and terminate games on a remote device and cancel an in-progress deployment. ## Functions | Function | Description | | - | - | | [WdRemoteCopy](https://docs.xbox.com/reference/remoting/functions/wdremotecopy.md) | Copies files between a local PC and a remote device. | | [WdCancelRemoteCopy](https://docs.xbox.com/reference/remoting/functions/wdcancelremotecopy.md) | Cancels an in-progress copy operation. | | [WdCreateCancellationHandle](https://docs.xbox.com/reference/remoting/functions/wdcreatecancellationhandle.md) | Creates a cancellation handle for cancelling a copy or delete operation. | | [WdCloseCancellationHandle](https://docs.xbox.com/reference/remoting/functions/wdclosecancellationhandle.md) | Closes a cancellation handle. | | [WdDuplicateCancellationHandle](https://docs.xbox.com/reference/remoting/functions/wdduplicatecancellationhandle.md) | Duplicates an existing cancellation handle. | | [WdLaunchRemoteGame](https://docs.xbox.com/reference/remoting/functions/wdlaunchremotegame.md) | Launches a game on a remote device. | | [WdResumeRemoteGame](https://docs.xbox.com/reference/remoting/functions/wdresumeremotegame.md) | Resumes the last game launched in suspended mode on a remote device. | | [WdTerminateRemoteGame](https://docs.xbox.com/reference/remoting/functions/wdterminateremotegame.md) | Terminates the last game launched on a remote device. | | [WdRegisterRemoteXboxGame](https://docs.xbox.com/reference/remoting/functions/wdregisterremotexboxgame.md) | Resolves and validates a remote folder path; does not perform platform game registration. | | [WdDeleteRemoteFiles](https://docs.xbox.com/reference/remoting/functions/wddeleteremotefiles.md) | Performs best-effort deletion of files and directories on a remote device. | | [WdCancelRemoteDelete](https://docs.xbox.com/reference/remoting/functions/wdcancelremotedelete.md) | Signals cancellation of the client wait for a delete operation. | ## Structures | Structure | Description | | - | - | | [WdCopyFileProgressInfo](https://docs.xbox.com/reference/remoting/structs/wdcopyfileprogressinfo.md) | Contains progress information for an individual file during a copy operation. | | [WdCopyOperationSummary](https://docs.xbox.com/reference/remoting/structs/wdcopyoperationsummary.md) | Contains summary progress information for the overall copy operation. | | [WdCopyOptions](https://docs.xbox.com/reference/remoting/structs/wdcopyoptions.md) | Specifies the direction and common root alias for a copy operation. | | [WdCopyStatusCallbacks](https://docs.xbox.com/reference/remoting/structs/wdcopystatuscallbacks.md) | Contains callback function pointers and settings for receiving copy status updates. | | [WdCopySearchOptions](https://docs.xbox.com/reference/remoting/structs/wdcopysearchoptions.md) | Specifies file and directory filter patterns for a copy operation. | | [WdCancellationHandle](https://docs.xbox.com/reference/remoting/structs/wdcancellationhandle.md) | An opaque handle used to cancel an in-progress copy or delete operation. | | [WdLaunchOptions](https://docs.xbox.com/reference/remoting/structs/wdlaunchoptions.md) | Specifies options for launching a game on a remote device. | | [WdDeleteFileProgressInfo](https://docs.xbox.com/reference/remoting/structs/wddeletefileprogressinfo.md) | Currently unused; no per-item delete progress data is produced. | | [WdDeleteOperationSummary](https://docs.xbox.com/reference/remoting/structs/wddeleteoperationsummary.md) | Currently unused; no delete progress summary is produced. | | [WdDeleteOptions](https://docs.xbox.com/reference/remoting/structs/wddeleteoptions.md) | Specifies options for a delete operation on a remote device. | | [WdDeleteStatusCallbacks](https://docs.xbox.com/reference/remoting/structs/wddeletestatuscallbacks.md) | Contains callback function pointers and settings that are currently ignored. | | [WdDeleteSearchOptions](https://docs.xbox.com/reference/remoting/structs/wddeletesearchoptions.md) | Specifies file and directory filter patterns for a delete operation. | ## Enumerations | Enumeration | Description | | - | - | | [WdCopyDirection](https://docs.xbox.com/reference/remoting/enums/wdcopydirection.md) | Specifies the direction of a copy operation. | | [WdLaunchMode](https://docs.xbox.com/reference/remoting/enums/wdlaunchmode.md) | Specifies the launch mode for a remote game. | | [WdCopyErrorSeverity](https://docs.xbox.com/reference/remoting/enums/wdcopyerrorseverity.md) | Specifies the severity of a copy error or warning message. | ## Callbacks | Callback | Description | | - | - | | [WdCopyFilesStatusCallback](https://docs.xbox.com/reference/remoting/callbacks/wdcopyfilesstatuscallback.md) | Called to report file copy progress during a copy operation. | | [WdCopyErrorCallback](https://docs.xbox.com/reference/remoting/callbacks/wdcopyerrorcallback.md) | Called to report error and warning messages during a copy operation. | | [WdDeleteProgressCallback](https://docs.xbox.com/reference/remoting/callbacks/wddeleteprogresscallback.md) | Currently unused; never invoked by `WdDeleteRemoteFiles`. | | [WdDeleteErrorCallback](https://docs.xbox.com/reference/remoting/callbacks/wddeleteerrorcallback.md) | Currently unused; never invoked by `WdDeleteRemoteFiles`. | ## Threading Model The XBOX PC Remote Iteration API is designed for single-threaded copy operations. The following rules apply: * **One copy at a time.** Only one [WdRemoteCopy](https://docs.xbox.com/reference/remoting/functions/wdremotecopy.md) call may be active at any given time, regardless of target device or destination path. Calling `WdRemoteCopy` while another copy is already in progress results in **undefined behavior**. * **Other functions are safe during a copy.** Functions such as [WdLaunchRemoteGame](https://docs.xbox.com/reference/remoting/functions/wdlaunchremotegame.md), [WdTerminateRemoteGame](https://docs.xbox.com/reference/remoting/functions/wdterminateremotegame.md), [WdResumeRemoteGame](https://docs.xbox.com/reference/remoting/functions/wdresumeremotegame.md), and [WdRegisterRemoteXboxGame](https://docs.xbox.com/reference/remoting/functions/wdregisterremotexboxgame.md) can be called from separate threads while a copy is in progress. * **Remote operations are blocking.** Functions such as `WdRemoteCopy` and `WdDeleteRemoteFiles` block waiting for an operation result, error, or observed cancellation. `WdCancelRemoteCopy` and `WdCancelRemoteDelete` are non-blocking. * **Cancellation is thread-safe.** [WdCancelRemoteCopy](https://docs.xbox.com/reference/remoting/functions/wdcancelremotecopy.md) and [WdCancelRemoteDelete](https://docs.xbox.com/reference/remoting/functions/wdcancelremotedelete.md) can be called from another thread to signal cancellation. * **No connection state between remote operations.** Each remote-operation call establishes its own connection to the remote device. There is no persistent session — for example, if the connection drops after [WdLaunchRemoteGame](https://docs.xbox.com/reference/remoting/functions/wdlaunchremotegame.md) completes, you can still call [WdTerminateRemoteGame](https://docs.xbox.com/reference/remoting/functions/wdterminateremotegame.md) once connectivity is restored. ## Retry Behavior The XBOX PC Remote Iteration API does **not** automatically retry failed operations at the API level. If an operation fails due to a network interruption or other transient error, the caller is responsible for retrying. * **No automatic retry.** If a copy operation fails (for example, due to loss of network connectivity), `WdRemoteCopy` returns an error. The caller must re-invoke the function to retry. * **No configurable timeout.** `WdRemoteCopy` does not impose a timeout on the copy operation. It continues transferring until complete, an error occurs, or it is cancelled via [WdCancelRemoteCopy](https://docs.xbox.com/reference/remoting/functions/wdcancelremotecopy.md). Under degraded network conditions, transfers may proceed very slowly rather than failing. * **Progress is preserved on failure.** Files that were successfully copied before a failure remain on the destination. When the caller retries the copy, the delta copy behavior ensures that only incomplete or missing files are transferred — previously copied files are not re-transferred. * **Disk space errors are reported.** If the destination device runs out of disk space during a copy, the operation fails with an error rather than hanging. * **Transport-level resilience.** The underlying transport layer handles low-level packet retransmission transparently. Minor network glitches (such as a single dropped packet) do not cause the operation to fail. However, sustained connectivity loss will eventually cause an error. * **Recommended retry pattern.** After a `WdRemoteCopy` failure, simply re-call `WdRemoteCopy` with the same parameters. Delta copy behavior minimizes redundant work by only transferring files that are missing or incomplete on the destination. ## Cancellation The XBOX PC Remote Iteration API provides a handle-based cancellation model for long-running copy and delete operations. The same [WdCancellationHandle](https://docs.xbox.com/reference/remoting/structs/wdcancellationhandle.md) type is used for both. The caller is responsible for the handle lifecycle: 1. Create a handle by calling [WdCreateCancellationHandle](https://docs.xbox.com/reference/remoting/functions/wdcreatecancellationhandle.md). 2. Pass the handle to [WdRemoteCopy](https://docs.xbox.com/reference/remoting/functions/wdremotecopy.md) via the `cancellationHandle` parameter. 3. From a separate thread, call [WdCancelRemoteCopy](https://docs.xbox.com/reference/remoting/functions/wdcancelremotecopy.md) with the handle to cancel the in-progress copy. `WdCancelRemoteCopy` is non-blocking. After cancellation is signaled, `WdRemoteCopy` may return `S_OK` or a failure. 4. After `WdRemoteCopy` returns, close the handle by calling [WdCloseCancellationHandle](https://docs.xbox.com/reference/remoting/functions/wdclosecancellationhandle.md). If multiple components need to reference the same cancellation handle, use [WdDuplicateCancellationHandle](https://docs.xbox.com/reference/remoting/functions/wdduplicatecancellationhandle.md) to duplicate it. Each copy must be closed independently. [WdDeleteRemoteFiles](https://docs.xbox.com/reference/remoting/functions/wddeleteremotefiles.md) follows the same handle-based model, using [WdCancelRemoteDelete](https://docs.xbox.com/reference/remoting/functions/wdcancelremotedelete.md) to signal cancellation. Observed cancellation stops the client wait and returns `S_OK` without confirming endpoint completion. Deletion already started on the endpoint continues independently; cancellation does not restore deleted items. ## Common Roots Common roots are pre-configured known locations on the remote device where games are typically copied to or launched from. Instead of specifying a full absolute path, callers can refer to these locations by alias using the `commonRootAlias` field in [WdCopyOptions](https://docs.xbox.com/reference/remoting/structs/wdcopyoptions.md) or [WdLaunchOptions](https://docs.xbox.com/reference/remoting/structs/wdlaunchoptions.md). For copy operations, the remote path is `destinationPath` for `CopyTo` and `sourcePath` for `CopyFrom`. If that path is absolute, the `commonRootAlias` is ignored. When it is relative, it is resolved against the common root identified by the alias. If no alias is specified, the default common root location is used. ## Error codes For a complete list of API-specific error codes, including descriptions, root causes, and troubleshooting guidance, see [XBOX PC Remote Iteration API Error Codes](https://docs.xbox.com/reference/remoting/error-codes.md). ## Versioning, Servicing, and Distribution For API NuGet, WinGet, and executable version numbers, see [XBOX PC Remote Iteration release versions](https://docs.xbox.com/reference/remoting/release-versions.md). The Remote Iteration Tools (RIT) API follows **Semantic Versioning 2.0.0** (`MAJOR.MINOR.PATCH`) to provide clear expectations around compatibility, upgrades, and long-term support. All public RIT API libraries are distributed via **NuGet**, enabling standard dependency management and update workflows. ### Versioning Model The compatibility expectations below apply to non-preview releases. For preview packages, consult the API-specific change history for declaration, layout, and behavior changes before upgrading. #### PATCH Releases `PATCH` updates deliver bug fixes and reliability improvements. These updates do **not** change API contracts or runtime behavior and are safe drop-in updates. Updating to a newer `PATCH` version does not require code changes. #### MINOR Releases `MINOR` updates introduce new APIs or evolve existing functionality in a backward-compatible manner. When APIs are planned for future change or removal, they are clearly marked as deprecated, giving developers time to migrate. Dependency updates are reviewed to ensure compatibility within the same `MAJOR` version. #### MAJOR Releases `MAJOR` updates represent intentional breaking changes. These releases may require code changes or dependency updates and are accompanied by clear migration guidance. Upgrading to a new `MAJOR` version is treated as an explicit, opt-in decision aligned with normal validation and release cycles. ### Servicing and Support Model Once a `MAJOR` or `MINOR` version of the RIT API is publicly released, it enters an active servicing period with a target support window of approximately **18 months**. During this time: * `PATCH` releases are greenlit to fix bugs and improve reliability for supported versions. * As new versions are released, and patches and minor changes improve existing versions and fix bugs, multiple `MAJOR` and `MINOR` versions may be serviced concurrently. * `PATCH` releases do **not** extend the servicing lifetime of a `MAJOR` or `MINOR` version. * New features are introduced only in newer `MINOR` or `MAJOR` releases and are not backported. After the servicing window ends, the version is retired and developers are expected to migrate to a newer supported `MAJOR` or `MINOR` release. ### Upgrade Expectations Developers are encouraged to stay current within a `MAJOR` version by adopting `PATCH` and `MINOR` updates. `MAJOR` version upgrades should be planned and validated explicitly to ensure compatibility with production workflows. ### API and wdEndpoint Version Compatibility The RIT API client library and the `wdEndpoint` running on the remote device should always be kept at compatible versions. Using a newer API version with an older `wdEndpoint` may result in `E_SERVERTOOOLD` errors or unexpected behavior. To guarantee correct behavior, full backward compatibility, and support for the latest API features, it is recommended to update `wdEndpoint` on all remote devices whenever the API client library is updated. Refer to the NuGet package release notes for minimum `wdEndpoint` version requirements. ## Requirements | Requirement | Value | | - | - | | **Header** | WdRemoteIteration.h | | **Library** | wdremoteapi.lib | | **NuGet Package** | [Microsoft.GDK.RemoteIterationClientApi](https://aka.ms/GameDevRemoteAPI) | | **Supported OS** | Windows 11 and later | | **Supported architectures** | x64, ARM64 | ## Conceptual documentation * [Release notes - XBOX PC Remote Tools (March 2026)](https://docs.xbox.com/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603.md) ## See also * [WdRemoteCopy](https://docs.xbox.com/reference/remoting/functions/wdremotecopy.md) * [WdCancelRemoteCopy](https://docs.xbox.com/reference/remoting/functions/wdcancelremotecopy.md) * [WdCreateCancellationHandle](https://docs.xbox.com/reference/remoting/functions/wdcreatecancellationhandle.md) * [WdLaunchRemoteGame](https://docs.xbox.com/reference/remoting/functions/wdlaunchremotegame.md) * [WdRegisterRemoteXboxGame](https://docs.xbox.com/reference/remoting/functions/wdregisterremotexboxgame.md) ## Related topics - [Release notes - XBOX PC Remote Tools (March 2026)](https://docs.xbox.com/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603.md) - [XBOX PC Remote Iteration release versions](https://docs.xbox.com/reference/remoting/release-versions.md) - [XBOX PC Remote Iteration API Error Codes](https://docs.xbox.com/reference/remoting/error-codes.md) - [XBOX PC Remote Tools](https://docs.xbox.com/tools/tools-pc/xbox-pc-remote-tools/index.md) - [WdRegisterRemoteXboxGame](https://docs.xbox.com/reference/remoting/functions/wdregisterremotexboxgame.md)