Skip to main content

XLaunchUri

Microsoft Game Development Kit(GDK) Launcher API는 게임이 URI를 호출하여 경험을 시작할 수 있는 메커니즘을 제공합니다.

구문

매개 변수

requestingUser   _In_opt_
형식: XUserHandle
요청을 수행하는 사용자를 식별하는 핸들을 정의합니다. uri   _In_z_
형식: char*
시작할 URI를 나타내는 문자열입니다.

반환 값

형식: HRESULT HRESULT 성공 또는 오류 코드입니다. 성공하면 S_OK를 반환하고, 그렇지 않으면 오류 코드를 반환합니다. 오류 코드 목록은 오류 코드를 참조하세요.

설명

이 함수는 시간에 민감한 스레드에서 호출하기에 안전하지 않습니다. 자세한 내용은 시간에 민감한 스레드를 참조하세요.
이 함수는 URI를 통해 다른 앱을 시작합니다. 또한 선택적 사용자 컨텍스트와 필수 URI를 받습니다. 성공하면 대상 URI가 시작됩니다. 그렇지 않으면 오류가 반환됩니다. 이 메서드는 시간에 중요한 것으로 간주되지 않으며, 내부 비동기 시스템 작업이 완료될 때까지 차단되고, 대상 URI가 시작되거나 오류가 발생할 때까지 대기합니다. 지정된 URI의 프로토콜 체계를 처리할 수 있는 앱이 없는 경우, 시스템은 해당 체계를 처리하는 애플리케이션을 Windows Store에서 검색할지 여부를 사용자에게 묻는 프롬프트를 표시합니다.

백그라운드로 시작

콘솔에서 appxmanifest 파일에 backgroundMediaPlayback 기능을 가진 유니버설 Windows 앱은 포그라운드가 아닌 백그라운드로 시작될 수 있습니다. 이렇게 하려면 URI 앞에 “ms-bgm-” 문자열을 붙이세요. 예를 들어, 백그라운드 미디어 애플리케이션이 “companion-music-app://” 프로토콜에 응답하는 경우, “ms-bgm-companion-music-app://” URI로 백그라운드에서 시작할 수 있습니다. 앱이 활성화를 받을 때 ProtocolActivatedEventArgs에서 얻은 URI에는 “ms-bgm-” 접두사가 포함되지 않습니다. 이런 방식으로 호출된 경우, XLaunchUri는 적합한 앱이 설치되지 않은 경우 사용자에게 프롬프트를 표시하지 않습니다. 대신, 게임이 2025년 4월 버전 이상의 GDK를 사용하는 경우, E_GAMEPACKAGE_NO_PACKAGE_IDENTIFIER를 반환합니다. 코드에서 이 반환 값을 확인하고 필요에 따라 사용자에게 조치 UI를 표시하는 데 사용할 수 있습니다. PC에서 XLaunchUri가 이런 방식으로 호출되면 정상적으로 시작하기 전에 URI의 시작 부분에서 “ms-bgm-”을 제거합니다. PC의 시스템 동작에는 다른 영향을 미치지 않습니다. 다음은 컴패니언 음악 애플리케이션을 시작하기 위해 XLaunchUri를 호출하는 예제입니다:

요구 사항

헤더: XLauncher.h 라이브러리: xgameruntime.lib 지원 플랫폼: Windows, XBOX One 계열 콘솔 및 XBOX Series 콘솔

개념 문서

함께 보기

XLauncher
마지막 수정일 2026년 8월 24일