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

# XUserAddByIdWithUiAsync

> XUserAddByIdWithUiAsync

# XUserAddByIdWithUiAsync

基于游戏邀请中的 XUID 异步将用户添加到游戏会话。此函数只应在响应游戏邀请时使用。

## Syntax

```cpp theme={null}
HRESULT XUserAddByIdWithUiAsync(  
         uint64_t userId,  
         XAsyncBlock* async  
)  
```

### Parameters

*userId*   \_In\_\
类型：uint64\_t

要添加的用户的 XUID。此 XUID 应通过分析在通过 [XGameInviteRegisterForEvent](/reference/system/xgameinvite/functions/xgameinviteregisterforevent) 注册的游戏回调中收到的 inviteUri 获得。

*async*   \_Inout\_\
类型：[XAsyncBlock\*](/reference/system/xasync/structs/xasyncblock)

用于轮询调用状态和检索调用结果的 [XAsyncBlock](/reference/system/xasync/structs/xasyncblock)。

### Return value

类型：HRESULT

HRESULT 成功或错误代码。
有关错误代码列表，请参阅[错误代码](/reference/errorcodes)。

## Remarks

**XUserAddByIdWithUiAsync** 启动异步操作，将用户添加到游戏。使用 [XUserAddByIdWithUiResult](/reference/system/xuser/functions/xuseraddbyidwithuiresult) 检索操作结果。

处理游戏邀请时，主机上始终存在这种可能性：游戏邀请中指定的人员的 XUID 不是已经登录到游戏的人员。**XUserAddByIdWithUiAsync** 允许游戏使用从邀请 URI 解析出的 XUID 添加该用户。

此函数将尝试添加用户而不显示 UI。可能显示 UI 的唯一原因是用户需要解决其令牌的问题。在主机上，显示 UI 的情况应该不常见。

如果用户未登录设备，**XUserAddByIdWithUiResult** 将返回 E\_GAMEUSER\_USER\_NOT\_FOUND。

必须通过调用 [XUserCloseHandle](/reference/system/xuser/functions/xuserclosehandle) 仅关闭一次从 XUsers API 检索到的每个 XUserHandle 句柄。

为了获取游戏邀请，开发者必须通过调用 [XGameInviteRegisterForEvent](/reference/system/xgameinvite/functions/xgameinviteregisterforevent) 订阅 [XGameInviteCallback](/reference/system/xgameinvite/functions/xgameinviteeventcallback)。调用此回调时，游戏应分析他们收到的 inviteUri，并确定收到该邀请的用户的 XUID。此时，游戏可能希望获取接收邀请的人员的 XUserHandle。以下代码演示了这一过程。

```cpp theme={null}
// Assumptions:
// 1. The game has previously registered for this callback using XGameInviteRegisterForEvent
// 2. The game has function: uint64_t GetXuidFromInviteUri(const char* inviteUri)
// 3. There is already a global task queue, g_GlobalQueue
 
void MyGameInviteEventCallback(void* context, const char* inviteUri)
{
   XAsyncBlock* asyncBlock = new XAsyncBlock();
   asyncBlock->queue = g_GlobalQueue;
   asyncBlock->callback = [](XAsyncBlock* ab)
   {
      XUserHandle userHandle;
      if(SUCCEEDED(XUserAddByIdWithUiResult(ab, &userHandle)))
      {
         // Copy this XUserHandle to some location that the game will use later or
         // Do whatever actions you want with this user

         XUserCloseHandle(userHandle);
      }
      else
      {
         // Since you didn't successfully add the user, setup your game state so that 
         // you are in a good place, likely a start menu
      }
      delete ab;
   }

   
   if(FAILED(XUserAddByIdWithUiAysnc(GetXuidFromInviteUri(inviteUri), asyncBlock)))
   {
      delete asyncBlock;
   }
}
```

## Requirements

**头文件：** XUser.h

**库：** xgameruntime.lib

**受支持的平台：** Windows、Steam Deck、XBOX One 系列主机和 XBOX Series 主机

## See also

[XUser](/reference/system/xuser/xuser_members)\
[XUserCloseHandle](/reference/system/xuser/functions/xuserclosehandle)


## Related topics

- [PFAuthenticationLoginWithXUserRequest](/zh-CN/services/playfab/api-references/c/pfauthenticationtypes/structs/pfauthenticationloginwithxuserrequest.md)
- [XUser](/zh-CN/reference/system/xuser/xuser_members.md)
- [面向 GDK 的 Unity C# API 包装器](/zh-CN/build/gdk-and-engines/unity/unity-api-wrappers.md)
- [XUserAddByIdWithUiResult](/zh-CN/reference/system/xuser/functions/xuseraddbyidwithuiresult.md)
- [XUserAddAsync](/zh-CN/reference/system/xuser/functions/xuseraddasync.md)