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

A API Launcher do Microsoft Game Development Kit (GDK) fornece um mecanismo que permite que os jogos iniciem uma experiência invocando um URI.

## Sintaxe

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

### Parâmetros

*requestingUser*   \_In\_opt\_\
Tipo: XUserHandle

Define um identificador que identifica o usuário que faz a solicitação.

*uri*   \_In\_z\_\
Tipo: char\*

Cadeia de caracteres que indica o URI a ser iniciado.

### Valor retornado

Tipo: HRESULT

Código HRESULT de êxito ou erro.

Retorna S\_OK se bem-sucedido; caso contrário, retorna um código de erro. Para obter uma lista de códigos de erro, consulte [Códigos de erro](/pt-BR/reference/errorcodes).

| Código de retorno | Descrição |
| - | - |
| S\_OK | A operação foi bem-sucedida. |
| E\_GAMEPACKAGE\_NO\_PACKAGE\_IDENTIFIER | O URI passado para essa função tentou iniciar um aplicativo em segundo plano, mas nenhum aplicativo adequado foi encontrado. Talvez ele não esteja instalado. |

## Comentários

<Note>Não é seguro chamar essa função em um thread sensível ao tempo. Para obter mais informações, consulte [Threads sensíveis ao tempo](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads).</Note>

Isso inicia outro aplicativo por meio de URI. Também aceita um contexto de usuário opcional e um URI obrigatório.

Se bem-sucedido, o URI de destino será iniciado. Caso contrário, um erro será retornado. Esse método não é considerado crítico em termos de tempo e fica bloqueado até que a operação assíncrona subjacente do sistema seja concluída e o URI de destino tenha sido iniciado ou tenha ocorrido um erro.

Se não houver nenhum aplicativo para tratar o esquema de protocolo do URI fornecido, o sistema exibirá um prompt perguntando ao usuário se ele deseja pesquisar na Windows Store um aplicativo que trate esse esquema.

### Iniciando em segundo plano

No console, os Aplicativos Universais do Windows que têm a funcionalidade [backgroundMediaPlayback](https://learn.microsoft.com/windows/uwp/audio-video-camera/background-audio) em seu arquivo appxmanifest podem ser iniciados em segundo plano, em vez de em primeiro plano. Para fazer isso, adicione a cadeia de caracteres "ms-bgm-" ao início do seu URI. Por exemplo, se o seu aplicativo de mídia em segundo plano responde ao protocolo "companion-music-app\://", você poderá iniciá-lo em segundo plano com o URI "ms-bgm-companion-music-app\://". Quando o aplicativo receber a ativação, o URI obtido de [ProtocolActivatedEventArgs](https://learn.microsoft.com/uwp/api/windows.applicationmodel.activation.protocolactivatedeventargs) não incluirá o prefixo "ms-bgm-".

Quando chamada dessa forma, XLaunchUri não mostra um prompt ao usuário quando nenhum aplicativo adequado está instalado. Em vez disso, se o seu jogo estiver usando a versão de abril de 2025 do GDK ou posterior, ela retornará E\_GAMEPACKAGE\_NO\_PACKAGE\_IDENTIFIER. Seu código pode verificar esse valor retornado e usá-lo para exibir uma interface do usuário de correção ao usuário, conforme apropriado.

No PC, quando XLaunchUri é chamada dessa forma, ela simplesmente remove "ms-bgm-" do início do URI antes de iniciá-lo normalmente. Não tem nenhum outro efeito no comportamento do sistema no PC.

Veja um exemplo de como chamar XLaunchUri para iniciar um aplicativo de música complementar:

```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;
}
```

## Requisitos

**Cabeçalho:** XLauncher.h

**Biblioteca:** xgameruntime.lib

**Plataformas compatíveis:** Windows, consoles da família XBOX One e consoles XBOX Series

## Documentação conceitual

* [Threads sensíveis ao tempo](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## Confira também

[XLauncher](/pt-BR/reference/system/xlauncher/xlauncher_members)


## Related topics

- [XLaunchUri](/reference/system/xlauncher/functions/xlaunchuri.md)
- [XLaunchNewGame](/reference/system/xgame/functions/xlaunchnewgame.md)