> ## 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="Quickstart" 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">
    원격 반복(remote iteration) 워크플로를 위한 명령줄 제어 도구입니다.
  </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 기기를 대상으로 하는 지속적 통합(CI) 파이프라인에서 빌드-배포-테스트 워크플로를 자동화할 때.
* 로컬 또는 테스트 랩에서 원격 Windows 기기로의 배포를 위해 커스텀 스튜디오 툴링을 만들거나 통합할 때.

## 사용하면 안 되는 때

* 최종 사용자 콘솔에 대한 게임의 소매 또는 프로덕션 배포에는 이 API를 사용하지 마세요.
* 두 원격 기기 간 파일 전송에는 이 API를 사용하지 마세요. 한쪽 엔드포인트는 반드시 로컬 PC여야 합니다.
* 원격 기기가 원격 개발용으로 페어링 및 구성되지 않은 경우에는 이 API를 사용하지 마세요.

## 사전 요구 사항

* **NuGet 패키지:** [Microsoft.GDK.RemoteIterationClientApi](https://aka.ms/GameDevRemoteAPI) 버전 0.1.0-preview\.26.3.6001 이상.
* **기기 페어링:** 로컬 PC와 원격 기기는 [XBOX PC Toolbox](/tools/tools-pc/xboxpctoolbox/xboxpctoolbox) 앱을 사용해 프로비저닝하여 페어링되고 상호 신뢰되어야 합니다.
* **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는 단일 스레드 복사 작업을 위해 설계되었습니다. 다음 규칙이 적용됩니다:

* **한 번에 하나의 복사만.** 대상 기기나 대상 경로와 관계없이 언제든지 활성화될 수 있는 [WdRemoteCopy](/reference/remoting/functions/wdremotecopy) 호출은 하나뿐입니다. 이미 다른 복사가 진행 중일 때 `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)을 사용하여 복제하세요. 각 복사본은 독립적으로 닫아야 합니다.

## 공통 루트(common roots)

공통 루트는 원격 기기에서 게임이 일반적으로 복사되거나 실행되는, 미리 구성된 알려진 위치입니다. 호출자는 전체 절대 경로를 지정하는 대신 [WdCopyOptions](/reference/remoting/structs/wdcopyoptions) 또는 [WdLaunchOptions](/reference/remoting/structs/wdlaunchoptions)의 `commonRootAlias` 필드를 사용해 별칭(alias)으로 이러한 위치를 참조할 수 있습니다.

`destinationPath`가 절대 경로이면 `commonRootAlias`는 무시됩니다. `destinationPath`가 상대 경로일 때는 별칭으로 식별되는 공통 루트를 기준으로 확인됩니다. 별칭이 지정되지 않으면 기본 공통 루트 위치가 사용됩니다.

## 오류 코드

설명, 근본 원인, 문제 해결 지침을 포함한 API별 오류 코드의 전체 목록은 [XBOX PC Remote Iteration API 오류 코드](/reference/remoting/error-codes)를 참조하세요.

## 버전 관리, 서비스 및 배포

Remote Iteration Tools (RIT) API는 호환성, 업그레이드 및 장기 지원에 관한 명확한 기대를 제공하기 위해 **Semantic Versioning 2.0.0**(`MAJOR.MINOR.PATCH`)을 따릅니다. 모든 공개 RIT API 라이브러리는 **NuGet**을 통해 배포되어 표준 종속성 관리 및 업데이트 워크플로를 지원합니다.

### 버전 관리 모델

#### PATCH 릴리스

`PATCH` 업데이트는 버그 수정 및 신뢰성 향상을 제공합니다. 이러한 업데이트는 API 계약이나 런타임 동작을 변경하지 **않으며**, 안전한 드롭인(drop-in) 업데이트입니다. 새 `PATCH` 버전으로 업데이트할 때는 코드 변경이 필요하지 않습니다.

#### MINOR 릴리스

`MINOR` 업데이트는 새 API를 도입하거나 하위 호환 방식으로 기존 기능을 발전시킵니다. 향후 변경 또는 제거가 예정된 API는 사용 중단(deprecated)으로 명확하게 표시되어, 개발자에게 마이그레이션할 시간을 제공합니다. 동일한 `MAJOR` 버전 내 호환성을 보장하기 위해 종속성 업데이트가 검토됩니다.

#### MAJOR 릴리스

`MAJOR` 업데이트는 의도적인 호환성 파괴 변경을 나타냅니다. 이러한 릴리스에는 코드 변경이나 종속성 업데이트가 필요할 수 있으며, 명확한 마이그레이션 지침이 함께 제공됩니다. 새 `MAJOR` 버전으로 업그레이드하는 것은 일반적인 검증 및 릴리스 주기에 맞춰진 명시적이고 옵트인(opt-in)된 결정으로 취급됩니다.

### 서비스 및 지원 모델

RIT API의 `MAJOR` 또는 `MINOR` 버전이 공개적으로 릴리스되면, 목표 지원 기간이 약 **18개월**인 활성 서비스 기간에 들어갑니다. 이 기간 동안:

* 지원되는 버전의 버그를 수정하고 신뢰성을 개선하기 위해 `PATCH` 릴리스가 승인됩니다.
* 새 버전이 릴리스되고 패치 및 마이너 변경으로 기존 버전이 개선되고 버그가 수정됨에 따라 여러 `MAJOR` 및 `MINOR` 버전이 동시에 서비스될 수 있습니다.
* `PATCH` 릴리스는 `MAJOR` 또는 `MINOR` 버전의 서비스 수명을 연장하지 **않습니다**.
* 새 기능은 새로운 `MINOR` 또는 `MAJOR` 릴리스에서만 도입되며 백포트되지 않습니다.

서비스 기간이 종료되면 해당 버전은 폐기되며, 개발자는 지원되는 최신 `MAJOR` 또는 `MINOR` 릴리스로 마이그레이션해야 합니다.

### 업그레이드 기대치

개발자는 `PATCH` 및 `MINOR` 업데이트를 채택하여 `MAJOR` 버전 내에서 최신 상태를 유지하는 것이 권장됩니다. `MAJOR` 버전 업그레이드는 프로덕션 워크플로와의 호환성을 보장하기 위해 명시적으로 계획되고 검증되어야 합니다.

### API와 wdEndpoint 버전 호환성

RIT API 클라이언트 라이브러리와 원격 기기에서 실행 중인 `wdEndpoint`는 항상 호환되는 버전으로 유지되어야 합니다. 이전 버전의 `wdEndpoint`와 함께 최신 API 버전을 사용하면 `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) 릴리스 노트](/ko/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603.md)
- [XBOX PC Remote Iteration API 오류 코드](/ko/reference/remoting/error-codes.md)
- [XBOX PC Remote Tools 사용 방법](/ko/tools/tools-pc/xbox-pc-remote-tools/how-to-use-tools.md)
- [XBOX PC Remote Tools](/ko/tools/tools-pc/xbox-pc-remote-tools/index.md)
- [WdRegisterRemoteXboxGame](/ko/reference/remoting/functions/wdregisterremotexboxgame.md)