Skip to main content

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

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.

Comentários

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

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

Confira também

XLauncher
Last modified on October 6, 2026