> ## 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 應透過剖析遊戲回呼中收到的 inviteUri 取得，該回呼
是透過 [XGameInviteRegisterForEvent](/zh-TW/reference/system/xgameinvite/functions/xgameinviteregisterforevent) 註冊的。

*async*   \_Inout\_\
類型：[XAsyncBlock\*](/zh-TW/reference/system/xasync/structs/xasyncblock)

用於輪詢呼叫狀態並擷取呼叫結果的 [XAsyncBlock](/zh-TW/reference/system/xasync/structs/xasyncblock)。

### 傳回值

類型：HRESULT

HRESULT 成功或錯誤碼。
如需錯誤碼清單，請參閱[錯誤碼](/zh-TW/reference/errorcodes)。

## 備註

**XUserAddByIdWithUiAsync** 會啟動非同步作業，將使用者新增至遊戲。請使用
[XUserAddByIdWithUiResult](/zh-TW/reference/system/xuser/functions/xuseraddbyidwithuiresult) 來擷取作業的結果。

處理遊戲邀請時，在主機上一律有可能發生遊戲邀請中指定的 XUID
並非已登入遊戲之人員的情況。**XUserAddByIdWithUiAsync**
可讓遊戲使用從邀請 URI 剖析出的 XUID 來新增該使用者。

此函式會嘗試在不顯示 UI 的情況下新增使用者。可能顯示 UI 的唯一原因，
是使用者需要解決其權杖的問題。在主機上，顯示 UI 的情況應該不常見。

如果使用者未登入裝置，**XUserAddByIdWithUiResult** 會傳回 E\_GAMEUSER\_USER\_NOT\_FOUND。

您從 XUsers API 擷取的每個 XUserHandle 控制代碼，都必須呼叫
[XUserCloseHandle](/zh-TW/reference/system/xuser/functions/xuserclosehandle) 關閉一次 (且僅限一次)。

若要取得遊戲邀請，開發人員必須呼叫 [XGameInviteRegisterForEvent](/zh-TW/reference/system/xgameinvite/functions/xgameinviteregisterforevent)
來訂閱 [XGameInviteCallback](/zh-TW/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](/zh-TW/reference/system/xuser/xuser_members)\
[XUserCloseHandle](/zh-TW/reference/system/xuser/functions/xuserclosehandle)


## Related topics

- [XUserAddByIdWithUiAsync](/reference/system/xuser/functions/xuseraddbyidwithuiasync.md)
- [PFAuthenticationLoginWithXUserRequest](/services/playfab/api-references/c/pfauthenticationtypes/structs/pfauthenticationloginwithxuserrequest.md)
- [XUser](/reference/system/xuser/xuser_members.md)