> ## 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. # XUserAddAsync > XUserAddAsync # XUserAddAsync Adiciona de forma assíncrona um usuário a uma sessão de jogo. ## Sintaxe ```cpp theme={null} HRESULT XUserAddAsync( XUserAddOptions options, XAsyncBlock* async ) ``` ### Parâmetros *options*   \_In\_\ Tipo: [XUserAddOptions](/pt-BR/reference/system/xuser/enums/xuseraddoptions) Opções para adicionar um usuário a uma sessão de jogo. *async*   \_Inout\_\ Tipo: [XAsyncBlock\*](/pt-BR/reference/system/xasync/structs/xasyncblock) Um [XAsyncBlock](/pt-BR/reference/system/xasync/structs/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](/pt-BR/reference/errorcodes). ## Comentários **XUserAddAsync** inicia uma operação assíncrona para adicionar um usuário ao jogo. Use [XUserAddResult](/pt-BR/reference/system/xuser/functions/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](/pt-BR/reference/system/xuser/enums/xuseraddoptions) ou [XUserAddOptions::AddDefaultUserAllowingUI](/pt-BR/reference/system/xuser/enums/xuseraddoptions) 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)](/pt-BR/build/core-features/common/user/gamecore-user-models): * 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](/pt-BR/reference/system/xuser/functions/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](/pt-BR/reference/system/xuser/enums/xuseraddoptions) 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](/pt-BR/reference/system/xuser/functions/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](/pt-BR/reference/system/xuser/functions/xuserregisterfordeviceassociationchanged). O exemplo a seguir demonstra como adicionar um usuário a uma sessão de jogo de forma assíncrona. ```cpp theme={null} HRESULT AddUserComplete(XAsyncBlock* ab) { unique_user_handle user; RETURN_IF_FAILED(XUserAddResult(ab, &user)); XUserLocalId userLocalId; XUserGetLocalId(user.get(), &userLocalId); auto iter = std::find_if( _users.begin(), _users.end(), [&userLocalId](const User& candidate) { XUserLocalId candidateUserLocalId; XUserGetLocalId(candidate.Handle(), &candidateUserLocalId); return candidateUserLocalId == userLocalId; }); // User already known if (iter != _users.end()) { appLog.AddLog("User already in list\n"); return S_OK; } try { _users.emplace_back(user.get()); _users.back().LoadGamerPicAsync(_queue); } CATCH_RETURN(); return S_OK; } HRESULT AddUser(bool allowGuests, bool silent) { auto asyncBlock = std::make_unique(); ZeroMemory(asyncBlock.get(), sizeof(*asyncBlock)); asyncBlock->queue = _queue; asyncBlock->context = this; asyncBlock->callback = [](XAsyncBlock* ab) { auto asyncBlock = std::unique_ptr(ab); LOG_IF_FAILED(static_cast(ab->context)->AddUserComplete(ab)); }; XUserAddOptions options = XUserAddOptions::None; if (allowGuests) { WI_SET_FLAG(options, XUserAddOptions::AllowGuests); } if (silent) { WI_SET_FLAG(options, XUserAddOptions::AddDefaultUserSilently); } if (SUCCEEDED_LOG(XUserAddAsync( options, asyncBlock.get()))) { // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* since the callback will take over ownership. // If the call fails, the std::unique_ptr will keep ownership and delete the XAsyncBlock* asyncBlock.release(); } return S_OK; } ``` ## 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 * [Executar tarefa de API do Microsoft Game Development Kit (GDK)](/pt-BR/build/core-features/common/async/async-libraries/async-library-xasync-example-run-gdk-task) * [Metas de design e melhorias da programação assíncrona](/pt-BR/build/core-features/common/async/async-whitepaper) * [Implementar a entrada do jogador no seu jogo](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/tutorials/pc-e2e-guide/e2e-services/e2e-user-sign-in) * [Introdução ao Game Chat 2](/pt-BR/services/xbox-services/multiplayer/chat/game-chat2/game-chat-2-intro) * [Usar a API C++ do Game Chat 2](/pt-BR/services/xbox-services/multiplayer/chat/game-chat2/using-game-chat-2) * [Implementar a entrada do jogador](/pt-BR/services/xbox-services/playfab-integration) ## Confira também [XUser](/pt-BR/reference/system/xuser/xuser_members) [XUserAddOptions](/pt-BR/reference/system/xuser/enums/xuseraddoptions) [XUserCloseHandle](/pt-BR/reference/system/xuser/functions/xuserclosehandle) ## Related topics - [XUserAddAsync](/reference/system/xuser/functions/xuseraddasync.md) - [User identity and XUser](/build/core-features/common/user/player-identity-xuser.md) - [XUserAddResult](/reference/system/xuser/functions/xuseraddresult.md) - [XUserAddOptions](/reference/system/xuser/enums/xuseraddoptions.md)