> ## 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 참조: 원격 Windows 기반 개발 기기에서 파일 복사, 게임 실행, 재개 및 종료를 수행하는 함수를 제공합니다. # XBOX PC Remote Iteration API 원격 Windows 기반 기기에서 파일을 복사하고 게임을 실행, 재개, 종료하는 기능을 제공합니다. > [!NOTE] > > 앱 기반 워크플로를 찾고 있나요? XBOX PC Toolbox 앱, `wdRemote` 및 `wdEndpoint` 명령줄 도구, Visual Studio 원격 디버거에 대해서는 [XBOX PC Remote Tools](https://docs.xbox.com/ko/tools/tools-pc/xbox-pc-remote-tools.md) 튜토리얼을 참조하세요. ## 시작하기 > **[XBOX PC Remote Tools 개요](https://docs.xbox.com/ko/tools/tools-pc/xbox-pc-remote-tools.md)** > > 원격 Windows 기기에서 프로비저닝, 배포, 실행, 디버깅 및 반복 작업을 수행합니다. > **[Quickstart](https://docs.xbox.com/ko/tools/tools-pc/xbox-pc-remote-tools/quickstart.md)** > > XBOX PC Toolbox 앱을 설치하고 개발 기기와 대상 기기를 페어링합니다. > **[wdRemote 명령줄 도구](https://docs.xbox.com/ko/tools/tools-pc/commandlinetools/gr-wdRemote.md)** > > 원격 반복(remote iteration) 워크플로를 위한 명령줄 제어 도구입니다. > **[FAQ 및 문제 해결](https://docs.xbox.com/ko/tools/tools-pc/xbox-pc-remote-tools/faq.md)** > > 자주 묻는 질문, 알려진 문제 및 해결 방법을 확인하세요. ## 개요 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](https://docs.xbox.com/ko/tools/tools-pc/xboxpctoolbox/xboxpctoolbox.md) 앱을 사용해 프로비저닝하여 페어링되고 상호 신뢰되어야 합니다. * **wdEndpoint:** 원격 기기에 `wdEndpoint`가 설치되어 실행 중이어야 합니다. [XBOX PC Toolbox](https://docs.xbox.com/ko/tools/tools-pc/xboxpctoolbox/xboxpctoolbox.md) 설정은 기본적으로 `wdEndpoint`를 설치하고 구성합니다. * **헤더 및 라이브러리:** `WdRemoteIteration.h`를 포함하고 `wdremoteapi.lib`에 링크하세요. ## 함수 | 함수 | 설명 | | - | - | | [WdRemoteCopy](https://docs.xbox.com/ko/reference/remoting/functions/wdremotecopy.md) | 로컬 PC와 원격 기기 간에 파일을 복사합니다. | | [WdCancelRemoteCopy](https://docs.xbox.com/ko/reference/remoting/functions/wdcancelremotecopy.md) | 진행 중인 복사 작업을 취소합니다. | | [WdCreateCancellationHandle](https://docs.xbox.com/ko/reference/remoting/functions/wdcreatecancellationhandle.md) | 복사 작업을 취소하기 위한 취소 핸들을 만듭니다. | | [WdCloseCancellationHandle](https://docs.xbox.com/ko/reference/remoting/functions/wdclosecancellationhandle.md) | 취소 핸들을 닫습니다. | | [WdDuplicateCancellationHandle](https://docs.xbox.com/ko/reference/remoting/functions/wdduplicatecancellationhandle.md) | 기존 취소 핸들을 복제합니다. | | [WdLaunchRemoteGame](https://docs.xbox.com/ko/reference/remoting/functions/wdlaunchremotegame.md) | 원격 기기에서 게임을 실행합니다. | | [WdResumeRemoteGame](https://docs.xbox.com/ko/reference/remoting/functions/wdresumeremotegame.md) | 원격 기기에서 마지막으로 일시 중단 모드로 실행된 게임을 재개합니다. | | [WdTerminateRemoteGame](https://docs.xbox.com/ko/reference/remoting/functions/wdterminateremotegame.md) | 원격 기기에서 마지막으로 실행된 게임을 종료합니다. | | [WdRegisterRemoteXboxGame](https://docs.xbox.com/ko/reference/remoting/functions/wdregisterremotexboxgame.md) | 원격 기기에 게임을 등록합니다. | ## 구조체 | 구조체 | 설명 | | - | - | | [WdCopyFileProgressInfo](https://docs.xbox.com/ko/reference/remoting/structs/wdcopyfileprogressinfo.md) | 복사 작업 중 개별 파일에 대한 진행 정보를 포함합니다. | | [WdCopyOperationSummary](https://docs.xbox.com/ko/reference/remoting/structs/wdcopyoperationsummary.md) | 전체 복사 작업에 대한 요약 진행 정보를 포함합니다. | | [WdCopyOptions](https://docs.xbox.com/ko/reference/remoting/structs/wdcopyoptions.md) | 복사 작업의 방향과 모드를 지정합니다. | | [WdCopyStatusCallbacks](https://docs.xbox.com/ko/reference/remoting/structs/wdcopystatuscallbacks.md) | 복사 상태 업데이트를 수신하기 위한 콜백 함수 포인터와 설정을 포함합니다. | | [WdCopySearchOptions](https://docs.xbox.com/ko/reference/remoting/structs/wdcopysearchoptions.md) | 복사 작업의 파일 및 디렉터리 필터 패턴을 지정합니다. | | [WdCancellationHandle](https://docs.xbox.com/ko/reference/remoting/structs/wdcancellationhandle.md) | 진행 중인 복사 작업을 취소하는 데 사용되는 불투명 핸들입니다. | | [WdLaunchOptions](https://docs.xbox.com/ko/reference/remoting/structs/wdlaunchoptions.md) | 원격 기기에서 게임을 실행하기 위한 옵션을 지정합니다. | ## 열거형 | 열거형 | 설명 | | - | - | | [WdCopyDirection](https://docs.xbox.com/ko/reference/remoting/enums/wdcopydirection.md) | 복사 작업의 방향을 지정합니다. | | [WdLaunchMode](https://docs.xbox.com/ko/reference/remoting/enums/wdlaunchmode.md) | 원격 게임의 실행 모드를 지정합니다. | | [WdCopyErrorSeverity](https://docs.xbox.com/ko/reference/remoting/enums/wdcopyerrorseverity.md) | 복사 오류 또는 경고 메시지의 심각도를 지정합니다. | ## 콜백 | 콜백 | 설명 | | - | - | | [WdCopyFilesStatusCallback](https://docs.xbox.com/ko/reference/remoting/callbacks/wdcopyfilesstatuscallback.md) | 복사 작업 중 파일 복사 진행률을 보고하기 위해 호출됩니다. | | [WdCopyErrorCallback](https://docs.xbox.com/ko/reference/remoting/callbacks/wdcopyerrorcallback.md) | 복사 작업 중 오류 및 경고 메시지를 보고하기 위해 호출됩니다. | ## 스레딩 모델 XBOX PC Remote Iteration API는 단일 스레드 복사 작업을 위해 설계되었습니다. 다음 규칙이 적용됩니다: * **한 번에 하나의 복사만.** 대상 기기나 대상 경로와 관계없이 언제든지 활성화될 수 있는 [WdRemoteCopy](https://docs.xbox.com/ko/reference/remoting/functions/wdremotecopy.md) 호출은 하나뿐입니다. 이미 다른 복사가 진행 중일 때 `WdRemoteCopy`를 호출하면 **정의되지 않은 동작**이 발생합니다. * **복사 중에도 다른 함수는 안전합니다.** 복사가 진행 중일 때 [WdLaunchRemoteGame](https://docs.xbox.com/ko/reference/remoting/functions/wdlaunchremotegame.md), [WdTerminateRemoteGame](https://docs.xbox.com/ko/reference/remoting/functions/wdterminateremotegame.md), [WdResumeRemoteGame](https://docs.xbox.com/ko/reference/remoting/functions/wdresumeremotegame.md), [WdRegisterRemoteXboxGame](https://docs.xbox.com/ko/reference/remoting/functions/wdregisterremotexboxgame.md) 같은 함수는 별도의 스레드에서 호출할 수 있습니다. * **모든 함수는 블로킹입니다.** API의 모든 함수는 작업이 완료되거나 실패할 때까지 호출한 스레드를 차단합니다. 특히 `WdRemoteCopy`는 전송 크기와 네트워크 조건에 따라 오랜 시간 동안 차단될 수 있습니다. * **취소는 스레드에 안전합니다.** [WdCancelRemoteCopy](https://docs.xbox.com/ko/reference/remoting/functions/wdcancelremotecopy.md)는 어떤 스레드에서든 호출할 수 있습니다. 여러 스레드가 동일한 작업을 동시에 취소하려고 하면 호출은 내부적으로 직렬화됩니다. 첫 번째 호출이 성공하고 이후 호출은 취소할 대상이 남아 있지 않으므로 오류를 반환합니다. * **호출 간 연결 상태가 없습니다.** 각 API 호출은 원격 기기에 대해 자체 연결을 설정합니다. 지속되는 세션은 없습니다. 예를 들어 [WdLaunchRemoteGame](https://docs.xbox.com/ko/reference/remoting/functions/wdlaunchremotegame.md) 완료 후 연결이 끊어져도, 연결이 복구되면 [WdTerminateRemoteGame](https://docs.xbox.com/ko/reference/remoting/functions/wdterminateremotegame.md)을 호출할 수 있습니다. ## 재시도 동작 XBOX PC Remote Iteration API는 API 수준에서 실패한 작업을 자동으로 재시도하지 **않습니다**. 네트워크 중단이나 기타 일시적 오류로 인해 작업이 실패한 경우, 재시도는 호출자의 책임입니다. * **자동 재시도 없음.** 복사 작업이 실패하면(예: 네트워크 연결 손실로 인해) `WdRemoteCopy`는 오류를 반환합니다. 재시도하려면 호출자가 함수를 다시 호출해야 합니다. * **구성 가능한 시간 초과 없음.** `WdRemoteCopy`는 복사 작업에 시간 초과를 부과하지 않습니다. 완료되거나, 오류가 발생하거나, [WdCancelRemoteCopy](https://docs.xbox.com/ko/reference/remoting/functions/wdcancelremotecopy.md)를 통해 취소될 때까지 계속 전송합니다. 저하된 네트워크 조건에서는 실패하는 대신 매우 느리게 전송이 진행될 수 있습니다. * **실패 시에도 진행 상황이 보존됩니다.** 실패 전에 성공적으로 복사된 파일은 대상에 남아 있습니다. 호출자가 복사를 재시도하면 델타 복사 동작 덕분에 불완전하거나 누락된 파일만 전송되며, 이전에 복사된 파일은 다시 전송되지 않습니다. * **디스크 공간 오류가 보고됩니다.** 복사 중 대상 기기의 디스크 공간이 부족해지면 작업이 중단되지 않고 오류로 실패합니다. * **전송 계층의 복원력.** 기반 전송 계층은 낮은 수준의 패킷 재전송을 투명하게 처리합니다. 사소한 네트워크 오류(예: 단일 패킷 손실)로는 작업이 실패하지 않습니다. 그러나 지속적인 연결 손실은 결국 오류를 유발합니다. * **권장 재시도 패턴.** `WdRemoteCopy` 실패 후에는 동일한 매개변수로 `WdRemoteCopy`를 다시 호출하기만 하면 됩니다. 델타 복사 동작은 대상에 누락되거나 불완전한 파일만 전송하여 중복 작업을 최소화합니다. ## 취소 XBOX PC Remote Iteration API는 장시간 실행되는 복사 작업을 위해 핸들 기반 취소 모델을 제공합니다. 핸들의 수명 주기는 호출자가 책임집니다: 1. [WdCreateCancellationHandle](https://docs.xbox.com/ko/reference/remoting/functions/wdcreatecancellationhandle.md)을 호출하여 핸들을 만듭니다. 2. `cancellationHandle` 매개변수를 통해 [WdRemoteCopy](https://docs.xbox.com/ko/reference/remoting/functions/wdremotecopy.md)에 핸들을 전달합니다. 3. 별도의 스레드에서 핸들과 함께 [WdCancelRemoteCopy](https://docs.xbox.com/ko/reference/remoting/functions/wdcancelremotecopy.md)를 호출하여 진행 중인 복사를 취소합니다. `WdCancelRemoteCopy`는 논블로킹입니다. 취소가 신호되면 `WdRemoteCopy`가 취소를 완료하고 `S_OK`를 반환합니다. 4. `WdRemoteCopy`가 반환된 후 [WdCloseCancellationHandle](https://docs.xbox.com/ko/reference/remoting/functions/wdclosecancellationhandle.md)을 호출하여 핸들을 닫습니다. 여러 구성 요소가 동일한 취소 핸들을 참조해야 하는 경우 [WdDuplicateCancellationHandle](https://docs.xbox.com/ko/reference/remoting/functions/wdduplicatecancellationhandle.md)을 사용하여 복제하세요. 각 복사본은 독립적으로 닫아야 합니다. ## 공통 루트(common roots) 공통 루트는 원격 기기에서 게임이 일반적으로 복사되거나 실행되는, 미리 구성된 알려진 위치입니다. 호출자는 전체 절대 경로를 지정하는 대신 [WdCopyOptions](https://docs.xbox.com/ko/reference/remoting/structs/wdcopyoptions.md) 또는 [WdLaunchOptions](https://docs.xbox.com/ko/reference/remoting/structs/wdlaunchoptions.md)의 `commonRootAlias` 필드를 사용해 별칭(alias)으로 이러한 위치를 참조할 수 있습니다. `destinationPath`가 절대 경로이면 `commonRootAlias`는 무시됩니다. `destinationPath`가 상대 경로일 때는 별칭으로 식별되는 공통 루트를 기준으로 확인됩니다. 별칭이 지정되지 않으면 기본 공통 루트 위치가 사용됩니다. ## 오류 코드 설명, 근본 원인, 문제 해결 지침을 포함한 API별 오류 코드의 전체 목록은 [XBOX PC Remote Iteration API 오류 코드](https://docs.xbox.com/ko/reference/remoting/error-codes.md)를 참조하세요. ## 버전 관리, 서비스 및 배포 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 | ## 개념 문서 > **[XBOX PC Remote Tools](https://docs.xbox.com/ko/tools/tools-pc/xbox-pc-remote-tools.md)** > > 원격 Windows 기기를 설정하고 XBOX PC Remote Tools를 사용하여 배포, 실행, 디버깅 및 반복 작업을 수행합니다. * [XBOX PC Remote Tools 릴리스 노트 (2026년 3월)](https://docs.xbox.com/ko/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603.md) ## 함께 보기 * [WdRemoteCopy](https://docs.xbox.com/ko/reference/remoting/functions/wdremotecopy.md) * [WdCancelRemoteCopy](https://docs.xbox.com/ko/reference/remoting/functions/wdcancelremotecopy.md) * [WdCreateCancellationHandle](https://docs.xbox.com/ko/reference/remoting/functions/wdcreatecancellationhandle.md) * [WdLaunchRemoteGame](https://docs.xbox.com/ko/reference/remoting/functions/wdlaunchremotegame.md) * [WdRegisterRemoteXboxGame](https://docs.xbox.com/ko/reference/remoting/functions/wdregisterremotexboxgame.md) ## Related topics - [릴리스 노트 - XBOX PC Remote Tools(2026년 3월)](https://docs.xbox.com/ko/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603.md) - [XBOX PC Remote Iteration API 오류 코드](https://docs.xbox.com/ko/reference/remoting/error-codes.md) - [XBOX PC Remote Iteration 릴리스 버전](https://docs.xbox.com/ko/reference/remoting/release-versions.md) - [XBOX PC Remote Tools](https://docs.xbox.com/ko/tools/tools-pc/xbox-pc-remote-tools/index.md) - [XBOX PC Remote Tools 사용 방법](https://docs.xbox.com/ko/tools/tools-pc/xbox-pc-remote-tools/how-to-use-tools.md)