> ## 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를 기반으로 게임 세션에 사용자를 비동기적으로 추가합니다. 이 함수는 게임 초대에 대한 응답으로만
사용해야 합니다.

## 구문

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

### 매개변수

*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)입니다.

### 반환값

형식: HRESULT

HRESULT 성공 또는 오류 코드입니다.
오류 코드 목록은 [Error Codes](/reference/errorcodes)를 참조하십시오.

## 설명

**XUserAddByIdWithUiAsync**는 게임에 사용자를 추가하는 비동기 작업을 시작합니다. 작업 결과를 가져오려면
[XUserAddByIdWithUiResult](/reference/system/xuser/functions/xuseraddbyidwithuiresult)를 사용합니다.

게임 초대를 처리할 때, 콘솔에서는 게임 초대에 지정된 사람의 XUID가 게임에 이미 로그인되어 있는 사람이 아닐 가능성이 항상 있습니다. **XUserAddByIdWithUiAsync**를 사용하면
게임이 초대 URI에서 파싱된 XUID를 사용하여 해당 사용자를 추가할 수 있습니다.

이 함수는 UI를 표시하지 않고 사용자를 추가하려고 시도합니다. UI가 표시될 수 있는 유일한 이유는
사용자가 토큰과 관련된 문제를 해결해야 하기 때문입니다. 콘솔에서는 UI 표시가 드물어야 합니다.

사용자가 장치에 로그인되어 있지 않은 경우, **XUserAddByIdWithUiResult**는 E\_GAMEUSER\_USER\_NOT\_FOUND를 반환합니다.

XUsers API에서 가져오는 각 XUserHandle 핸들은
[XUserCloseHandle](/reference/system/xuser/functions/xuserclosehandle)을 호출하여 한 번만 닫아야 합니다.

게임 초대를 받으려면 개발자는 [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;
   }
}
```

## 요구 사항

**헤더:** XUser.h

**라이브러리:** xgameruntime.lib

**지원되는 플랫폼:** Windows, , Steam Deck, XBOX One 계열 콘솔 및 XBOX Series 콘솔

## 함께 보기

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


## Related topics

- [PFAuthenticationLoginWithXUserRequest](/ko/services/playfab/api-references/c/pfauthenticationtypes/structs/pfauthenticationloginwithxuserrequest.md)
- [XUser](/ko/reference/system/xuser/xuser_members.md)
- [GDK용 Unity C# API 래퍼](/ko/build/gdk-and-engines/unity/unity-api-wrappers.md)
- [XUserAddByIdWithUiResult](/ko/reference/system/xuser/functions/xuseraddbyidwithuiresult.md)
- [사용자 ID 및 XUser](/ko/build/core-features/common/user/player-identity-xuser.md)