Microsoft GDK(게임 개발 키트) 시작 관리자 API는 URI를 호출하여 게임이 사용자 환경을 시작할 수 있게 해주는 메커니즘을 제공합니다.
구문
HRESULT XLaunchUri(
XUserHandle requestingUser,
const char* uri
)
매개 변수
requestingUser _In_opt_
형식: XUserHandle
요청을 수행하는 사용자를 식별하는 핸들을 정의합니다.
uri _In_z_
형식: char*
시작할 URI를 나타내는 문자열입니다.
반환 값
형식: HRESULT
HRESULT 성공 또는 오류 코드입니다.
성공한 경우 S_OK를 반환하고, 그렇지 않으면 오류 코드를 반환합니다. 오류 코드 목록은 오류 코드를 참조하세요.
| 반환 코드 | 설명 |
|---|---|
| S_OK | 작업이 성공했습니다. |
| E_GAMEPACKAGE_NO_PACKAGE_IDENTIFIER | 이 함수에 전달된 URI가 백그라운드로 앱을 시작하려고 했지만 적합한 앱을 찾을 수 없습니다. 설치되지 않을 수 있습니다. |
비고
참고 항목
이 함수는 시간에 민감한 스레드에서 호출하는 것이 안전하지 않습니다. 자세한 내용은 시간에 민감한 스레드를 참조하세요.
그러면 URI를 통해 다른 앱이 시작됩니다. 또한 선택적인 사용자 컨텍스트 및 필수 URI를 사용합니다.
성공하면 대상 URI가 시작됩니다. 그렇지 않으면 오류가 반환됩니다. 이 메서드는 시간에 중요한 것으로 간주되지 않으며, 기본 비동기 시스템 작업이 완료될 때까지, 그리고 대상 URI가 시작되었거나 오류가 발생할 때까지 차단됩니다.
지정된 URI의 프로토콜 스키마를 처리할 앱이 없으면 이 스키마를 처리하는 응용 프로그램을 Windows Store에서 검색할지 여부를 묻는 프롬프트를 사용자에게 표시합니다.
백그라운드로 시작
콘솔에서는 appxmanifest 파일에 backgroundMediaPlayback 기능이 있는 유니버설 Windows 앱을 포그라운드 대신 백그라운드로 시작할 수 있습니다. 이렇게 하려면 URI 앞에 "ms-bgm-" 문자열을 추가합니다. 예를 들어 백그라운드 미디어 애플리케이션이 프로토콜 "companion-music-app://"에 응답하는 경우 URI "ms-bgm-companion-music-app://"을 사용하여 백그라운드로 시작할 수 있습니다. 앱이 활성화를 받으면 ProtocolActivatedEventArgs 에서 가져온 URI에는 "ms-bgm-" 접두사를 포함하지 않습니다.
이러한 방식으로 호출되면 XLaunchUri는 적절한 앱이 설치되지 않은 경우 사용자에게 프롬프트를 표시하지 않습니다. 대신 게임이 2025년 4월 버전의 GDK 이상을 사용하는 경우 E_GAMEPACKAGE_NO_PACKAGE_IDENTIFIER 반환합니다. 코드는 이 반환 값에 대해 검사 사용자에게 수정 UI를 적절하게 표시하는 데 사용할 수 있습니다.
PC에서 XLaunchUri가 이러한 방식으로 호출되면 정상적으로 시작하기 전에 URI의 시작 부분에서 "ms-bgm-"을 제거하기만 하면 됩니다. PC의 시스템 동작에는 다른 영향을 주지 않습니다.
다음은 XLaunchUri를 호출하여 도우미 음악 애플리케이션을 시작하는 예제입니다.
HRESULT BeginPlayingMusic(XUserHandle user)
{
// Launch a well-known companion music application.
// The game and app both need to agree on the URI scheme.
HRESULT hr = XLaunchUri(user, "ms-bgm-companion-music-app://launch?play=true");
if (hr == E_GAMEPACKAGE_NO_PACKAGE_IDENTIFIER)
{
// If the music app isn't installed, launch the store page so the user can download it.
return XLaunchUri(user, "ms-windows-store://pdp/?ProductId=9FAKESTOREID");
}
return hr;
}
요구 사항
헤더: XLauncher.h
라이브러리: xgameruntime.lib
지원되는 플랫폼: Windows, Xbox One 패밀리 콘솔 및 Xbox Series 콘솔