Compartilhar via


XUserAddByIdWithUiAsync

Asynchronously adds a user to a game session based on a XUID from a game invite. This function should only be used in response to a game invite.

Syntax

HRESULT XUserAddByIdWithUiAsync(  
         uint64_t userId,  
         XAsyncBlock* async  
)  

Parameters

userId   _In_
Type: uint64_t

XUID of the user to add. This XUID should be obtained by parsing the inviteUri received in the game's callback that was registered with XGameInviteRegisterForEvent.

async   _Inout_
Type: XAsyncBlock*

An XAsyncBlock for polling for the call's status and retrieving call results.

Return value

Type: HRESULT

HRESULT success or error code. For a list of error codes, see Error Codes.

Remarks

XUserAddByIdWithUiAsync starts an asynchronous operation to add a user to the game. Use XUserAddByIdWithUiResult to retrieve the results of the operation.

When dealing with game invites, there is always the possibility on console that the XUID of the person specified in the game invite isn't the person who is already signed into the game. The XUserAddByIdWithUiAsync allows the game to add that user using the XUID that is parsed from the invite URI.

This function will attempt to add the user without showing UI. The only reason UI may show is because the user needs to resolve an issue with their token. On console, showing UI should be uncommon.

If the user is not signed into the device, XUserAddByIdWithUiResult will return E_GAMEUSER_USER_NOT_FOUND.

You must close each XUserHandle handle you retrieve from an XUsers API only once by calling XUserCloseHandle.

In order to get game invites, developers must subscribe to the XGameInviteCallback by calling XGameInviteRegisterForEvent. When this callback is invoked, games should parse the inviteUri they get back and determine the XUID of the user who is getting that invite. At that point, the game may want to get an XUserHandle for the person getting the invite. The following code demonstrates how this works.

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

Header: XUser.h

Library: xgameruntime.lib

Supported platforms: Windows, Xbox One family consoles and Xbox Series consoles

See also

XUser
XUserCloseHandle