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

指定用于添加用户的选项。

## Syntax

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

## Constants

| 常量                       | 说明                                                                                |
| ------------------------ | --------------------------------------------------------------------------------- |
| None                     | 没有选项。                                                                             |
| AddDefaultUserSilently   | 获取启动游戏的用户，且不弹出任何 UI。                                                              |
| AllowGuests              | 用户选取器 UI 中将包含来宾。                                                                  |
| AddDefaultUserAllowingUI | 尝试以静默方式获取启动游戏的初始用户。如果系统可以获取该用户而不弹出任何 UI，则会尝试这样做。如果该用户需要给予同意或修复帐户问题，将显示 UI 来解决该问题。 |

## Remarks

如果开发者反复调用 [XUserAddAsync](/reference/system/xuser/functions/xuseraddasync) 并将 *options* 设置为 XUserAddOptions::AddDefaultUserSilently，则应了解一些边缘情况：

* 如果反复调用此项，并且我们知道启动游戏的默认用户，它将返回相同的用户。
* 如果先前已知的默认用户已注销，并且只有一个用户登录设备，它会将该用户标记为新的“默认”用户并返回。
* 如果先前已知的默认用户已注销，并且有多个用户登录设备，它将返回 E\_GAMEUSER\_NO\_DEFAULT\_USER。
* 在开发者启动中，将作为默认用户的用户是自动登录用户，可通过在 DevHome 中将该用户设置为自动登录用户，或者通过使用 [xbconfig（NDA 主题）](/tools/tools-console/commandlinetools/xbconfig) DefaultUser 来指定。

如果默认用户不可用\*，[XUserAddResult](/reference/system/xuser/functions/xuseraddresult) 将返回 E\_GAMEUSER\_NO\_DEFAULT\_USER。必须调用 [XUserAddAsync](/reference/system/xuser/functions/xuseraddasync)，并且 *options* 不设置为 XUserAddOptions::AddDefaultUserSilently。

如果开发者反复调用 [XUserAddAsync](/reference/system/xuser/functions/xuseraddasync) 并将 *options* 设置为 XUserAddOptions::AddDefaultUserAllowingUI，也应了解一些边缘情况。这些情况与静默 UI 情况非常相似（但不完全相同）：

* 如果反复调用此项，并且我们知道启动游戏的默认用户，它将返回相同的用户。
* 如果先前已知的默认用户已注销，并且只有一个用户登录设备，它会将该用户标记为新的“默认”用户并返回。
* 如果最初启动游戏的用户已注销，并且用户数为 0 或多于 1，则系统将显示 UI 以获取用户，然后将该用户设置为默认。

在 [XUserAddAsync](/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;
}
```

## Requirements

**头文件：** XUser.h

**受支持的平台：** Windows、XBOX One 系列主机和 XBOX Series 主机

## See also

[XUser](/reference/system/xuser/xuser_members)

[XUserAddAsync](/reference/system/xuser/functions/xuseraddasync)

[XUserAddResult](/reference/system/xuser/functions/xuseraddresult)


## Related topics

- [XUserAddResult](/zh-CN/reference/system/xuser/functions/xuseraddresult.md)
- [XUserAddAsync](/zh-CN/reference/system/xuser/functions/xuseraddasync.md)
- [XUser](/zh-CN/reference/system/xuser/xuser_members.md)
- [访客用户概述](/zh-CN/build/core-features/common/user/users-guest-overview.md)
- [XUserPrivilegeOptions](/zh-CN/reference/system/xuser/enums/xuserprivilegeoptions.md)