> ## 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.

# XUserAddAsync

> XUserAddAsync

# XUserAddAsync

以非同步方式將使用者新增至遊戲工作階段。

## 語法

```cpp theme={null}
HRESULT XUserAddAsync(  
         XUserAddOptions options,  
         XAsyncBlock* async  
)  
```

### 參數

*options*   \_In\_\
類型：[XUserAddOptions](/zh-TW/reference/system/xuser/enums/xuseraddoptions)

將使用者新增至遊戲工作階段的選項。

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

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

### 傳回值

類型：HRESULT

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

## 備註

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

除非將
[XUserAddOptions::AddDefaultUserSilently](/zh-TW/reference/system/xuser/enums/xuseraddoptions) 或
[XUserAddOptions::AddDefaultUserAllowingUI](/zh-TW/reference/system/xuser/enums/xuseraddoptions) 傳遞給 *options* 參數，否則 **XUserAddAsync** 一律會顯示帳戶選擇器 UI。

如果您使用 **XUserAddOptions::AddDefaultUserSilently**，**XUserAddAsync** 不會顯示 UI。

使用[簡化使用者模型 (NDA 主題)](/zh-TW/build/core-features/common/user/gamecore-user-models) 時，此函式有一些注意事項：

* 使用簡化使用者模型時，開發人員應確定 *options* 設定為
  **XUserAddOptions::AddDefaultUserSilently**：
* 在主機上，除非已有預設使用者登入，否則使用簡化使用者模型的鬆散部署遊戲將不允許
  啟動。
* 在 PC 上，使用簡化使用者模型的鬆散部署遊戲可以在沒有使用者的情況下啟動；
  不過，當遊戲呼叫 **XUserAddAsync** 時，如果沒有任何人登入，遊戲將會
  終止，並啟動 PC Bootstrapper 來協助使用者登入。只要使用者已完全登入 XBOX Live，
  後續啟動就會正常運作。

如果開發人員以設定為 **XUserAddOptions::AddDefaultUserSilently** 的 *options* 重複
呼叫 **XUserAddAsync**，應該了解一些邊緣案例：

* 如果您重複呼叫此函式，且我們知道啟動遊戲的預設使用者，則會傳回同一位使用者。
* 如果先前已知的預設使用者已登出，且裝置上只有一位已登入的使用者，則會
  將該使用者標示為新的「預設」使用者並傳回該使用者。
* 如果先前已知的預設使用者已登出，且裝置上有多位已登入的使用者，則
  會傳回 E\_GAMEUSER\_NO\_DEFAULT\_USER。

如果沒有可用的預設使用者，[XUserAddResult](/zh-TW/reference/system/xuser/functions/xuseraddresult) 會傳回
E\_GAMEUSER\_NO\_DEFAULT\_USER。您必須以未設定為
**XUserAddOptions::AddDefaultUserSilently** 的 *options* 呼叫 **XUserAddAsync**。

如果開發人員以設定為 **XUserAddOptions::AddDefaultUserAllowingUI** 的 *options* 重複呼叫
**XUserAddAsync**，也應該了解一些邊緣案例。這些案例與無訊息 UI 的情況
非常類似 (但不完全相同)：

* 如果您重複呼叫此函式，且我們知道啟動遊戲的預設使用者，則會傳回同一位使用者。
* 如果先前已知的預設使用者已登出，且裝置上只有一位已登入的使用者，則會將該使用者標示為新的「預設」使用者並傳回該使用者。
* 如果最初啟動遊戲的使用者已登出，且使用者數目為 0 或超過 1 位，系統會顯示 UI 以取得使用者，然後將該使用者設定為預設使用者。

您無法將 [XUserAddOptions::AllowGuests](/zh-TW/reference/system/xuser/enums/xuseraddoptions) 與
**XUserAddOptions::AddDefaultUserSilently** 一起使用。來賓不能是預設使用者。無論目前的平台是否支援來賓，
您都可以放心使用 **XUserAddOptions::AllowGuests**。

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

**XUserAddAsync** 成功完成時會執行輸入裝置配對。如果由於 **XUserAddOptions::AddDefaultUserSilently** 或 **XUserAddOptions::AddDefaultUserAllowingUI** 選項而在沒有 UI 的情況下自動登入，則系統中指派給使用者的輸入裝置會傳播至遊戲。如果登入時顯示了 UI，則選取該使用者的輸入裝置會指派給該使用者。

可以透過 [XUserRegisterForDeviceAssociationChanged](/zh-TW/reference/system/xuser/functions/xuserregisterfordeviceassociationchanged) 方法追蹤裝置關聯。

下列範例示範如何以非同步方式將使用者新增至遊戲工作階段。

```cpp theme={null}
HRESULT AddUserComplete(XAsyncBlock* ab)
{
    unique_user_handle user;
    RETURN_IF_FAILED(XUserAddResult(ab, &user));

    XUserLocalId userLocalId;
    XUserGetLocalId(user.get(), &userLocalId);

    auto iter = std::find_if(
        _users.begin(),
        _users.end(),
        [&userLocalId](const User& candidate)
    {
        XUserLocalId candidateUserLocalId;
        XUserGetLocalId(candidate.Handle(), &candidateUserLocalId);
        return candidateUserLocalId == userLocalId;
    });

    // User already known
    if (iter != _users.end())
    {
        appLog.AddLog("User already in list\n");
        return S_OK;
    }

    try
    {
        _users.emplace_back(user.get());
        _users.back().LoadGamerPicAsync(_queue);
    }
    CATCH_RETURN();

    return S_OK;
}

HRESULT AddUser(bool allowGuests, bool silent)
{
    auto asyncBlock = std::make_unique<XAsyncBlock>();
    ZeroMemory(asyncBlock.get(), sizeof(*asyncBlock));
    asyncBlock->queue = _queue;
    asyncBlock->context = this;
    asyncBlock->callback = [](XAsyncBlock* ab)
    {
        auto asyncBlock = std::unique_ptr<XAsyncBlock>(ab);
        LOG_IF_FAILED(static_cast<UserWindow*>(ab->context)->AddUserComplete(ab));
    };

    XUserAddOptions options = XUserAddOptions::None;

    if (allowGuests)
    {
        WI_SET_FLAG(options, XUserAddOptions::AllowGuests);
    }

    if (silent)
    {
        WI_SET_FLAG(options, XUserAddOptions::AddDefaultUserSilently);
    }

    if (SUCCEEDED_LOG(XUserAddAsync(
        options,
        asyncBlock.get())))
    {
        // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* since the callback will take over ownership.
        // If the call fails, the std::unique_ptr will keep ownership and delete the XAsyncBlock*
        asyncBlock.release();
    }

    return S_OK;
}
```

## 需求

**標頭：** XUser.h

**程式庫：** xgameruntime.lib

**支援的平台：** Windows、Steam Deck、XBOX One 系列主機和 XBOX Series 主機

## 概念文件

* [執行 Microsoft Game Development Kit (GDK) API 工作](/zh-TW/build/core-features/common/async/async-libraries/async-library-xasync-example-run-gdk-task)
* [非同步程式設計的設計目標與改進](/zh-TW/build/core-features/common/async/async-whitepaper)
* [在遊戲中實作玩家登入](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/tutorials/pc-e2e-guide/e2e-services/e2e-user-sign-in)
* [Game Chat 2 簡介](/zh-TW/services/xbox-services/multiplayer/chat/game-chat2/game-chat-2-intro)
* [使用 Game Chat 2 C++ API](/zh-TW/services/xbox-services/multiplayer/chat/game-chat2/using-game-chat-2)
* [實作玩家登入](/zh-TW/services/xbox-services/playfab-integration)

## 另請參閱

[XUser](/zh-TW/reference/system/xuser/xuser_members)

[XUserAddOptions](/zh-TW/reference/system/xuser/enums/xuseraddoptions)

[XUserCloseHandle](/zh-TW/reference/system/xuser/functions/xuserclosehandle)


## Related topics

- [XUserAddAsync](/reference/system/xuser/functions/xuseraddasync.md)
- [User identity and XUser](/build/core-features/common/user/player-identity-xuser.md)
- [XUserAddResult](/reference/system/xuser/functions/xuseraddresult.md)
- [XUserAddOptions](/reference/system/xuser/enums/xuseraddoptions.md)
- [Unity C# API wrappers for the GDK](/build/gdk-and-engines/unity/unity-api-wrappers.md)