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 を呼び出して XUser API から取得した各 XUserHandle ハンドルを 1 回だけ閉じる必要があります。

ゲームへの招待を受けるには、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