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

# XUserAddOptions

> XUserAddOptions

# XUserAddOptions

指定新增使用者的選項。

## 語法

```cpp theme={null}
enum class XUserAddOptions  : uint32_t  
{  
    None = 0x00,  
    AddDefaultUserSilently = 0x01,  
    AllowGuests = 0x02,  
    AddDefaultUserAllowingUI = 0x04,
}  
```

## 常數

| 常數 | 描述 |
| - | - |
| None | 無選項。 |
| AddDefaultUserSilently | 在不彈出任何 UI 的情況下取得啟動遊戲的使用者。 |
| AllowGuests | 使用者選擇器 UI 中將包含來賓。 |
| AddDefaultUserAllowingUI | 嘗試以無訊息方式取得最初啟動遊戲的使用者。如果系統能在不彈出任何 UI 的情況下取得該使用者，便會嘗試這麼做。如果該使用者需要提供同意或修正帳戶問題，則會顯示 UI 以解決問題。 |

## 備註

如果開發人員以設定為 XUserAddOptions::AddDefaultUserSilently 的 *options* 重複呼叫
[XUserAddAsync](/zh-TW/reference/system/xuser/functions/xuseraddasync)，應該了解一些邊緣案例：

* 如果您重複呼叫此函式，且我們知道啟動遊戲的預設使用者，則會傳回同一位使用者。
* 如果先前已知的預設使用者已登出，且裝置上只有一位已登入的使用者，則會
  將該使用者標示為新的「預設」使用者並傳回該使用者。
* 如果先前已知的預設使用者已登出，且裝置上有多位已登入的使用者，則
  會傳回 E\_GAMEUSER\_NO\_DEFAULT\_USER。
* 在開發人員啟動中，預設使用者是自動登入使用者，您可以在 DevHome 中將該使用者設定為自動登入使用者，或使用 [xbconfig (NDA 主題)](/zh-TW/tools/tools-console/commandlinetools/xbconfig) DefaultUser 來指定。

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

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

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

在 [XUserAddAsync](/zh-TW/reference/system/xuser/functions/xuseraddasync) 中，您無法將 XUserAddOptions::AllowGuests 與
XUserAddOptions::AddDefaultUserSilently 一起使用。來賓不能是預設使用者。

即使目前的平台不支援來賓，您仍可使用 XUserAddOptions::AllowGuests。

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

```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

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

## 另請參閱

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

[XUserAddAsync](/zh-TW/reference/system/xuser/functions/xuseraddasync)

[XUserAddResult](/zh-TW/reference/system/xuser/functions/xuseraddresult)


## Related topics

- [XUserAddOptions](/reference/system/xuser/enums/xuseraddoptions.md)
- [XUserAddResult](/reference/system/xuser/functions/xuseraddresult.md)
- [XUserAddAsync](/reference/system/xuser/functions/xuseraddasync.md)