XUserAddByIdWithUiAsync

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

语法

HRESULT XUserAddByIdWithUiAsync(  
         uint64_t userId,  
         XAsyncBlock* async  
)  

参数

userId _In_
类型：uint64_t

要添加的用户的 XUID。 此 XUID 应通过以下方式获得：分析在注册到 XGameInviteRegisterForEvent 的游戏回调中收到的 inviteUri。

async _Inout_
类型：XAsyncBlock*

用于轮询调用的状态和检索调用结果的 XAsyncBlock。

返回值

类型：HRESULT

HRESULT 成功或错误代码。 有关错误代码的列表，请参阅错误代码。

备注

XUserAddByIdWithUiAsync 启动一个异步操作来将用户添加到游戏。 使用 XUserAddByIdWithUiResult 检索该操作的结果。

在处理游戏邀请时，主机上始终存在这样的可能，即游戏邀请中指定的人员的 XUID 并非已经登录游戏的人员。 XUserAddByIdWithUiAsync 允许游戏使用通过邀请 URI 分析的 XUID 来添加该用户。

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

如果用户未登录设备，XUserAddByIdWithUiResult 将返回 E_GAMEUSER_USER_NOT_FOUND。

必须通过调用 XUserCloseHandle 关闭从 XUsers API 检索到的每个 XUserHandle 句柄，且仅关闭一次。

为了获得游戏邀请，开发人员必须通过调用 XGameInviteRegisterForEvent 订阅 XGameInviteCallback。 调用此回调后，游戏将分析其收到的 inviteUri，并确定获得该邀请的用户的 XUID。 此时，游戏可能需要获取受邀者的 XUserHandle。 以下代码演示了其工作原理。

// 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;
   }
}

要求

头文件：XUser.h

库：xgameruntime.lib

支持平台：Windows、Xbox One 系列主机和 Xbox Series 主机

另请参阅

XUser
XUserCloseHandle