Skip to main content

XUserAddAsync

Adiciona de forma assíncrona um usuário a uma sessão de jogo.

Sintaxe

Parâmetros

options   _In_
Tipo: XUserAddOptions
Opções para adicionar um usuário a uma sessão de jogo. async   _Inout_
Tipo: XAsyncBlock*
Um XAsyncBlock para sondar o status da chamada e recuperar os resultados da chamada.

Valor retornado

Tipo: HRESULT Código de sucesso ou de erro HRESULT. Para obter uma lista de códigos de erro, consulte Códigos de erro.

Comentários

XUserAddAsync inicia uma operação assíncrona para adicionar um usuário ao jogo. Use XUserAddResult para recuperar os resultados da operação. XUserAddAsync sempre exibe uma interface do usuário do Seletor de Contas, a menos que XUserAddOptions::AddDefaultUserSilently ou XUserAddOptions::AddDefaultUserAllowingUI seja passado para o parâmetro options. Se você usar XUserAddOptions::AddDefaultUserSilently, XUserAddAsync não exibirá uma interface do usuário. Há algumas considerações sobre esta função ao usar o modelo de usuário simplificado (tópico sob NDA):
  • Com o modelo de usuário simplificado, os desenvolvedores devem garantir que options esteja definido como XUserAddOptions::AddDefaultUserSilently:
  • No console, jogos implantados de forma solta que usam o modelo de usuário simplificado não poderão ser iniciados, a menos que já haja um usuário padrão conectado.
  • No PC, jogos implantados de forma solta que usam o modelo de usuário simplificado podem ser iniciados sem um usuário; no entanto, quando o jogo chamar XUserAddAsync, se ninguém estiver conectado, o jogo será encerrado e o PC Bootstrapper será iniciado para ajudar um usuário a entrar. As inicializações seguintes funcionarão normalmente, desde que o usuário esteja totalmente conectado ao XBOX Live.
Há alguns casos extremos que os desenvolvedores devem conhecer se chamarem repetidamente XUserAddAsync com options definido como XUserAddOptions::AddDefaultUserSilently:
  • Se você chamar isso repetidamente e soubermos qual é o usuário padrão que iniciou o jogo, o mesmo usuário será retornado.
  • Se o usuário padrão conhecido anteriormente tiver saído e houver apenas um usuário conectado ao dispositivo, esse usuário será marcado como o novo usuário “padrão” e retornado.
  • Se o usuário padrão conhecido anteriormente tiver saído e houver vários usuários conectados ao dispositivo, será retornado E_GAMEUSER_NO_DEFAULT_USER.
Se um usuário padrão não estiver disponível, XUserAddResult retornará E_GAMEUSER_NO_DEFAULT_USER. Você deve chamar XUserAddAsync com options não definido como XUserAddOptions::AddDefaultUserSilently. Também há alguns casos extremos que os desenvolvedores devem conhecer se chamarem repetidamente XUserAddAsync com options definido como XUserAddOptions::AddDefaultUserAllowingUI. Eles são muito semelhantes (mas não idênticos) ao caso silencioso:
  • Se você chamar isso repetidamente e soubermos qual é o usuário padrão que iniciou o jogo, o mesmo usuário será retornado.
  • Se o usuário padrão conhecido anteriormente tiver saído e houver apenas um usuário conectado ao dispositivo, esse usuário será marcado como o novo usuário “padrão” e retornado.
  • Se o usuário que iniciou o jogo originalmente tiver saído e o número de usuários for 0 ou mais de 1, o sistema exibirá a interface do usuário para obter o usuário e, em seguida, definirá esse usuário como padrão.
Você não pode usar XUserAddOptions::AllowGuests com XUserAddOptions::AddDefaultUserSilently. Um convidado não pode ser o usuário padrão. Você pode usar XUserAddOptions::AllowGuests com segurança, independentemente de a plataforma atual oferecer suporte a convidados. Você deve fechar cada identificador XUserHandle recuperado de uma API XUsers apenas uma vez, chamando XUserCloseHandle. O emparelhamento de dispositivos de entrada é realizado após a conclusão bem-sucedida de XUserAddAsync. Se a entrada ocorreu automaticamente sem interface do usuário devido às opções XUserAddOptions::AddDefaultUserSilently ou XUserAddOptions::AddDefaultUserAllowingUI, os dispositivos de entrada atribuídos ao usuário no sistema serão propagados para o título. Se a interface do usuário foi exibida para a entrada, o dispositivo de entrada que selecionou o usuário será atribuído a esse usuário. A associação de dispositivos pode ser rastreada por meio do método XUserRegisterForDeviceAssociationChanged. O exemplo a seguir demonstra como adicionar um usuário a uma sessão de jogo de forma assíncrona.

Requisitos

Cabeçalho: XUser.h Biblioteca: xgameruntime.lib Plataformas com suporte: Windows, Steam Deck, consoles da família XBOX One e consoles XBOX Series

Documentação conceitual

Confira também

XUser XUserAddOptions XUserCloseHandle
Last modified on October 6, 2026