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를 반환합니다.

XUsers API에서 검색한 각 XUserHandle 핸들은 XUserCloseHandle을 호출하여 한 번만 닫아야 합니다.

게임 초대를 얻으려면 개발자는 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