​

XBOX PC Remote Iteration API

원격 Windows 기반 기기에서 파일을 복사하고 게임을 실행, 재개, 종료하는 기능을 제공합니다.

​

시작하기

​

개요

XBOX PC Remote Iteration API는 원격 Windows 기기를 대상으로 하는 PC 기반 개발 워크플로를 가능하게 합니다. 로컬 PC와 원격 기기 사이에서 게임 파일을 전송하고, 원격 기기에서 게임 프로세스를 실행 및 관리하며, 원격 실행을 위해 게임을 등록하는 C 함수 집합을 제공합니다. 이 API는 게임 개발 중 긴밀한 반복 루프를 위해 설계되었으며, 개발자가 로컬에서 빌드한 뒤 수동 파일 관리 없이 원격 하드웨어에 배포하고 테스트할 수 있게 합니다.

​

사용해야 할 때

• 개발 중 로컬 PC에서 원격 Windows 기기로 게임 빌드를 배포할 때.
• 반복 빌드 중 전송 시간을 최소화하기 위해 원격 기기에 업데이트된 파일(델타 복사)을 복사할 때.
• 개발 PC에서 원격 기기의 게임 프로세스를 실행, 일시 중단, 재개, 종료할 때.
• 원격 Windows 기기를 대상으로 하는 지속적 통합(CI) 파이프라인에서 빌드-배포-테스트 워크플로를 자동화할 때.
• 로컬 또는 테스트 랩에서 원격 Windows 기기로의 배포를 위해 커스텀 스튜디오 툴링을 만들거나 통합할 때.

​

사용하면 안 되는 때

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

​

사전 요구 사항

• NuGet 패키지: Microsoft.GDK.RemoteIterationClientApi 버전 0.1.0-preview.26.3.6001 이상.
• 기기 페어링: 로컬 PC와 원격 기기는 XBOX PC Toolbox 앱을 사용해 프로비저닝하여 페어링되고 상호 신뢰되어야 합니다.
• wdEndpoint: 원격 기기에 wdEndpoint가 설치되어 실행 중이어야 합니다. XBOX PC Toolbox 설정은 기본적으로 wdEndpoint를 설치하고 구성합니다.
• 헤더 및 라이브러리: WdRemoteIteration.h를 포함하고 wdremoteapi.lib에 링크하세요.

​

함수

​

구조체

​

열거형

​

콜백

​

스레딩 모델

XBOX PC Remote Iteration API는 단일 스레드 복사 작업을 위해 설계되었습니다. 다음 규칙이 적용됩니다:

• 한 번에 하나의 복사만. 대상 기기나 대상 경로와 관계없이 언제든지 활성화될 수 있는 WdRemoteCopy 호출은 하나뿐입니다. 이미 다른 복사가 진행 중일 때 WdRemoteCopy를 호출하면 정의되지 않은 동작이 발생합니다.
• 복사 중에도 다른 함수는 안전합니다. 복사가 진행 중일 때 WdLaunchRemoteGame, WdTerminateRemoteGame, WdResumeRemoteGame, WdRegisterRemoteXboxGame 같은 함수는 별도의 스레드에서 호출할 수 있습니다.
• 모든 함수는 블로킹입니다. API의 모든 함수는 작업이 완료되거나 실패할 때까지 호출한 스레드를 차단합니다. 특히 WdRemoteCopy는 전송 크기와 네트워크 조건에 따라 오랜 시간 동안 차단될 수 있습니다.
• 취소는 스레드에 안전합니다. WdCancelRemoteCopy는 어떤 스레드에서든 호출할 수 있습니다. 여러 스레드가 동일한 작업을 동시에 취소하려고 하면 호출은 내부적으로 직렬화됩니다. 첫 번째 호출이 성공하고 이후 호출은 취소할 대상이 남아 있지 않으므로 오류를 반환합니다.
• 호출 간 연결 상태가 없습니다. 각 API 호출은 원격 기기에 대해 자체 연결을 설정합니다. 지속되는 세션은 없습니다. 예를 들어 WdLaunchRemoteGame 완료 후 연결이 끊어져도, 연결이 복구되면 WdTerminateRemoteGame을 호출할 수 있습니다.

​

재시도 동작

XBOX PC Remote Iteration API는 API 수준에서 실패한 작업을 자동으로 재시도하지 않습니다. 네트워크 중단이나 기타 일시적 오류로 인해 작업이 실패한 경우, 재시도는 호출자의 책임입니다.

• 자동 재시도 없음. 복사 작업이 실패하면(예: 네트워크 연결 손실로 인해) WdRemoteCopy는 오류를 반환합니다. 재시도하려면 호출자가 함수를 다시 호출해야 합니다.
• 구성 가능한 시간 초과 없음. WdRemoteCopy는 복사 작업에 시간 초과를 부과하지 않습니다. 완료되거나, 오류가 발생하거나, WdCancelRemoteCopy를 통해 취소될 때까지 계속 전송합니다. 저하된 네트워크 조건에서는 실패하는 대신 매우 느리게 전송이 진행될 수 있습니다.
• 실패 시에도 진행 상황이 보존됩니다. 실패 전에 성공적으로 복사된 파일은 대상에 남아 있습니다. 호출자가 복사를 재시도하면 델타 복사 동작 덕분에 불완전하거나 누락된 파일만 전송되며, 이전에 복사된 파일은 다시 전송되지 않습니다.
• 디스크 공간 오류가 보고됩니다. 복사 중 대상 기기의 디스크 공간이 부족해지면 작업이 중단되지 않고 오류로 실패합니다.
• 전송 계층의 복원력. 기반 전송 계층은 낮은 수준의 패킷 재전송을 투명하게 처리합니다. 사소한 네트워크 오류(예: 단일 패킷 손실)로는 작업이 실패하지 않습니다. 그러나 지속적인 연결 손실은 결국 오류를 유발합니다.
• 권장 재시도 패턴. WdRemoteCopy 실패 후에는 동일한 매개변수로 WdRemoteCopy를 다시 호출하기만 하면 됩니다. 델타 복사 동작은 대상에 누락되거나 불완전한 파일만 전송하여 중복 작업을 최소화합니다.

​

취소

XBOX PC Remote Iteration API는 장시간 실행되는 복사 작업을 위해 핸들 기반 취소 모델을 제공합니다. 핸들의 수명 주기는 호출자가 책임집니다:

1. WdCreateCancellationHandle을 호출하여 핸들을 만듭니다.
2. cancellationHandle 매개변수를 통해 WdRemoteCopy에 핸들을 전달합니다.
3. 별도의 스레드에서 핸들과 함께 WdCancelRemoteCopy를 호출하여 진행 중인 복사를 취소합니다. WdCancelRemoteCopy는 논블로킹입니다. 취소가 신호되면 WdRemoteCopy가 취소를 완료하고 S_OK를 반환합니다.
4. WdRemoteCopy가 반환된 후 WdCloseCancellationHandle을 호출하여 핸들을 닫습니다.

여러 구성 요소가 동일한 취소 핸들을 참조해야 하는 경우 WdDuplicateCancellationHandle을 사용하여 복제하세요. 각 복사본은 독립적으로 닫아야 합니다.

​

공통 루트(common roots)

공통 루트는 원격 기기에서 게임이 일반적으로 복사되거나 실행되는, 미리 구성된 알려진 위치입니다. 호출자는 전체 절대 경로를 지정하는 대신 WdCopyOptions 또는 WdLaunchOptions의 commonRootAlias 필드를 사용해 별칭(alias)으로 이러한 위치를 참조할 수 있습니다. destinationPath가 절대 경로이면 commonRootAlias는 무시됩니다. destinationPath가 상대 경로일 때는 별칭으로 식별되는 공통 루트를 기준으로 확인됩니다. 별칭이 지정되지 않으면 기본 공통 루트 위치가 사용됩니다.

​

오류 코드

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

​

버전 관리, 서비스 및 배포

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 패키지 릴리스 노트를 참조하세요.

​

요구 사항

​

개념 문서

• XBOX PC Remote Tools 릴리스 노트 (2026년 3월)

​

함께 보기

• WdRemoteCopy
• WdCancelRemoteCopy
• WdCreateCancellationHandle
• WdLaunchRemoteGame
• WdRegisterRemoteXboxGame