> ## 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 Agrega de forma asincrónica un usuario a una sesión de juego. ## Sintaxis ```cpp theme={null} HRESULT XUserAddAsync( XUserAddOptions options, XAsyncBlock* async ) ``` ### Parámetros *options*   \_In\_\ Tipo: [XUserAddOptions](/reference/system/xuser/enums/xuseraddoptions) Opciones para agregar un usuario a una sesión de juego. *async*   \_Inout\_\ Tipo: [XAsyncBlock\*](/reference/system/xasync/structs/xasyncblock) Un [XAsyncBlock](/reference/system/xasync/structs/xasyncblock) para sondear el estado de la llamada y recuperar los resultados de la llamada. ### Valor devuelto Tipo: HRESULT Código de error o de operación correcta HRESULT. Para obtener una lista de códigos de error, consulte [Códigos de error](/reference/errorcodes). ## Comentarios **XUserAddAsync** inicia una operación asincrónica para agregar un usuario al juego. Use [XUserAddResult](/reference/system/xuser/functions/xuseraddresult) para recuperar los resultados de la operación. **XUserAddAsync** siempre muestra una interfaz de usuario del selector de cuentas a menos que se pase [XUserAddOptions::AddDefaultUserSilently](/reference/system/xuser/enums/xuseraddoptions) o [XUserAddOptions::AddDefaultUserAllowingUI](/reference/system/xuser/enums/xuseraddoptions) al parámetro *options*. Si usa **XUserAddOptions::AddDefaultUserSilently**, **XUserAddAsync** no muestra ninguna interfaz de usuario. Hay algunas consideraciones con esta función al usar el [modelo de usuario simplificado (tema NDA)](/build/core-features/common/user/gamecore-user-models): * Con el modelo de usuario simplificado, los desarrolladores deben asegurarse de que *options* esté establecido en **XUserAddOptions::AddDefaultUserSilently**: * En consola, los juegos implementados de forma dispersa que usan el modelo de usuario simplificado no podrán iniciarse a menos que ya haya un usuario predeterminado con sesión iniciada. * En PC, los juegos implementados de forma dispersa que usan el modelo de usuario simplificado se pueden iniciar sin un usuario; sin embargo, cuando el juego llame a **XUserAddAsync**, si nadie ha iniciado sesión, el juego se terminará y se iniciará el arrancador de PC para ayudar a que un usuario inicie sesión. Los inicios posteriores funcionarán sin problemas siempre que el usuario tenga la sesión totalmente iniciada en XBOX Live. Hay algunos casos extremos que los desarrolladores deben conocer si llaman repetidamente a **XUserAddAsync** con *options* establecido en **XUserAddOptions::AddDefaultUserSilently**: * Si llama a esta función repetidamente y se conoce el usuario predeterminado que inició el juego, devolverá ese mismo usuario. * Si el usuario predeterminado conocido anteriormente ha cerrado sesión y solo hay un usuario con sesión iniciada en el dispositivo, marcará a ese usuario como el nuevo usuario "predeterminado" y lo devolverá. * Si el usuario predeterminado conocido anteriormente ha cerrado sesión y hay varios usuarios con sesión iniciada en el dispositivo, devolverá E\_GAMEUSER\_NO\_DEFAULT\_USER. Si no hay disponible un usuario predeterminado, [XUserAddResult](/reference/system/xuser/functions/xuseraddresult) devuelve E\_GAMEUSER\_NO\_DEFAULT\_USER. Debe llamar a **XUserAddAsync** con *options* no establecido en **XUserAddOptions::AddDefaultUserSilently**. También hay algunos casos extremos que los desarrolladores deben conocer si llaman repetidamente a **XUserAddAsync** con *options* establecido en **XUserAddOptions::AddDefaultUserAllowingUI**. Son muy similares (pero no idénticos) al caso de interfaz de usuario silenciosa: * Si llama a esta función repetidamente y se conoce el usuario predeterminado que inició el juego, devolverá ese mismo usuario. * Si el usuario predeterminado conocido anteriormente ha cerrado sesión y solo hay un usuario con sesión iniciada en el dispositivo, marcará a ese usuario como el nuevo usuario "predeterminado" y lo devolverá. * Si el usuario que inició inicialmente el juego ha cerrado sesión y el número de usuarios es 0 o más de 1, el sistema mostrará una interfaz de usuario para obtener el usuario y, a continuación, establecerá a ese usuario como el predeterminado. No puede usar [XUserAddOptions::AllowGuests](/reference/system/xuser/enums/xuseraddoptions) con **XUserAddOptions::AddDefaultUserSilently**. Un invitado no puede ser el usuario predeterminado. Puede usar de forma segura **XUserAddOptions::AllowGuests** independientemente de si la plataforma actual admite invitados. Debe cerrar cada identificador **XUserHandle** que recupere de una API de **XUsers** una sola vez llamando a [XUserCloseHandle](/reference/system/xuser/functions/xuserclosehandle). El emparejamiento de dispositivos de entrada se realiza cuando **XUserAddAsync** se completa correctamente. Si el inicio de sesión se produjo automáticamente sin interfaz de usuario debido a las opciones **XUserAddOptions::AddDefaultUserSilently** o **XUserAddOptions::AddDefaultUserAllowingUI**, los dispositivos de entrada asignados al usuario en el sistema se propagan al título. Si se mostró la interfaz de usuario para el inicio de sesión, el dispositivo de entrada que seleccionó al usuario se asigna a ese usuario. La asociación de dispositivos se puede realizar un seguimiento a través del método [XUserRegisterForDeviceAssociationChanged](/reference/system/xuser/functions/xuserregisterfordeviceassociationchanged). El siguiente ejemplo muestra cómo agregar de forma asincrónica un usuario a una sesión de juego. ```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 **Encabezado:** XUser.h **Biblioteca:** xgameruntime.lib **Plataformas compatibles:** Windows, Steam Deck, consolas de la familia XBOX One y consolas XBOX Series ## Documentación conceptual * [Ejecutar una tarea de la API de Microsoft Game Development Kit (GDK)](/build/core-features/common/async/async-libraries/async-library-xasync-example-run-gdk-task) * [Objetivos de diseño y mejoras de la programación asincrónica](/build/core-features/common/async/async-whitepaper) * [Implementar el inicio de sesión del jugador en su juego](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/tutorials/pc-e2e-guide/e2e-services/e2e-user-sign-in) * [Introducción a Game Chat 2](/services/xbox-services/multiplayer/chat/game-chat2/game-chat-2-intro) * [Uso de la API de C++ de Game Chat 2](/services/xbox-services/multiplayer/chat/game-chat2/using-game-chat-2) * [Implementar el inicio de sesión del jugador](/services/xbox-services/playfab-integration) ## Consulte también [XUser](/reference/system/xuser/xuser_members) [XUserAddOptions](/reference/system/xuser/enums/xuseraddoptions) [XUserCloseHandle](/reference/system/xuser/functions/xuserclosehandle) ## Related topics - [XUserAddOptions](/es/reference/system/xuser/enums/xuseraddoptions.md) - [XUserAddResult](/es/reference/system/xuser/functions/xuseraddresult.md) - [Contenedores de API de C# de Unity para el GDK](/es/build/gdk-and-engines/unity/unity-api-wrappers.md) - [Identidad de usuario y XUser](/es/build/core-features/common/user/player-identity-xuser.md) - [Automatización desatendida de XUser](/es/build/core-features/common/user/users-headless-automation.md)