> ## 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.

# XLaunchUri

> XLaunchUri

# XLaunchUri

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

## 구문

```cpp theme={null}
HRESULT XLaunchUri(  
         XUserHandle requestingUser,  
         const char* uri  
)  
```

### 매개 변수

*requestingUser*   \_In\_opt\_\
형식: XUserHandle

요청을 수행하는 사용자를 식별하는 핸들을 정의합니다.

*uri*   \_In\_z\_\
형식: char\*

시작할 URI를 나타내는 문자열입니다.

### 반환 값

형식: HRESULT

HRESULT 성공 또는 오류 코드입니다.

성공하면 S\_OK를 반환하고, 그렇지 않으면 오류 코드를 반환합니다. 오류 코드 목록은 [오류 코드](/reference/errorcodes)를 참조하세요.

| 반환 코드                                   | 설명                                                                     |
| --------------------------------------- | ---------------------------------------------------------------------- |
| S\_OK                                   | 작업이 성공했습니다.                                                            |
| E\_GAMEPACKAGE\_NO\_PACKAGE\_IDENTIFIER | 이 함수에 전달된 URI가 앱을 백그라운드로 시작하려고 했지만, 적합한 앱을 찾을 수 없습니다. 설치되지 않았을 수 있습니다. |

## 설명

<Note>이 함수는 시간에 민감한 스레드에서 호출하기에 안전하지 않습니다. 자세한 내용은 [시간에 민감한 스레드](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)를 참조하세요.</Note>

이 함수는 URI를 통해 다른 앱을 시작합니다. 또한 선택적 사용자 컨텍스트와 필수 URI를 받습니다.

성공하면 대상 URI가 시작됩니다. 그렇지 않으면 오류가 반환됩니다. 이 메서드는 시간에 중요한 것으로 간주되지 않으며, 내부 비동기 시스템 작업이 완료될 때까지 차단되고, 대상 URI가 시작되거나 오류가 발생할 때까지 대기합니다.

지정된 URI의 프로토콜 체계를 처리할 수 있는 앱이 없는 경우, 시스템은 해당 체계를 처리하는 애플리케이션을 Windows Store에서 검색할지 여부를 사용자에게 묻는 프롬프트를 표시합니다.

### 백그라운드로 시작

콘솔에서 appxmanifest 파일에 [backgroundMediaPlayback](https://learn.microsoft.com/windows/uwp/audio-video-camera/background-audio) 기능을 가진 유니버설 Windows 앱은 포그라운드가 아닌 백그라운드로 시작될 수 있습니다. 이렇게 하려면 URI 앞에 "ms-bgm-" 문자열을 붙이세요. 예를 들어, 백그라운드 미디어 애플리케이션이 "companion-music-app\://" 프로토콜에 응답하는 경우, "ms-bgm-companion-music-app\://" URI로 백그라운드에서 시작할 수 있습니다. 앱이 활성화를 받을 때 [ProtocolActivatedEventArgs](https://learn.microsoft.com/uwp/api/windows.applicationmodel.activation.protocolactivatedeventargs)에서 얻은 URI에는 "ms-bgm-" 접두사가 포함되지 않습니다.

이런 방식으로 호출된 경우, XLaunchUri는 적합한 앱이 설치되지 않은 경우 사용자에게 프롬프트를 표시하지 않습니다. 대신, 게임이 2025년 4월 버전 이상의 GDK를 사용하는 경우, E\_GAMEPACKAGE\_NO\_PACKAGE\_IDENTIFIER를 반환합니다. 코드에서 이 반환 값을 확인하고 필요에 따라 사용자에게 조치 UI를 표시하는 데 사용할 수 있습니다.

PC에서 XLaunchUri가 이런 방식으로 호출되면 정상적으로 시작하기 전에 URI의 시작 부분에서 "ms-bgm-"을 제거합니다. PC의 시스템 동작에는 다른 영향을 미치지 않습니다.

다음은 컴패니언 음악 애플리케이션을 시작하기 위해 XLaunchUri를 호출하는 예제입니다:

```cpp theme={null}
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 콘솔

## 개념 문서

* [시간에 민감한 스레드](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## 함께 보기

[XLauncher](/reference/system/xlauncher/xlauncher_members)


## Related topics

- [XLaunchNewGame](/ko/reference/system/xgame/functions/xlaunchnewgame.md)
- [XLauncher](/ko/reference/system/xlauncher/xlauncher_members.md)
- [XR-109 앱 간 연결](/ko/publishing/certification/xr/xr-109.md)
- [원격 복구 URI](/ko/reference/deviceportal/remote/atoc-rest-remote.md)
- [무인 설치 URI](/ko/reference/deviceportal/unattendedsetup/atoc-rest-unattendedsetup.md)