> ## 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를 표시하지 않고 해당 사용자를 가져올 수 있으면 그렇게 시도합니다. 해당 사용자가 동의를 제공하거나 계정 문제를 해결해야 하는 경우, 문제를 해결하기 위해 UI가 표시됩니다. |

## 설명

*options*를 XUserAddOptions::AddDefaultUserSilently로 설정하여 [XUserAddAsync](/reference/system/xuser/functions/xuseraddasync)를 반복해서 호출하는 경우, 개발자가 알아야 할 몇 가지 예외적인 상황이 있습니다.

* 이 함수를 반복해서 호출할 때 게임을 시작한 기본 사용자를 알고 있는 경우, 동일한 사용자를 반환합니다.
* 이전에 알려진 기본 사용자가 로그아웃했고, 장치에 로그인된 사용자가 한 명뿐인 경우, 해당 사용자를 새 "기본" 사용자로 표시하고 반환합니다.
* 이전에 알려진 기본 사용자가 로그아웃했고, 장치에 로그인된 사용자가 여러 명인 경우, 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를 반환합니다. XUserAddOptions::AddDefaultUserSilently로 설정되지 않은 *options*로 [XUserAddAsync](/reference/system/xuser/functions/xuseraddasync)를 호출해야 합니다.

*options*를 XUserAddOptions::AddDefaultUserAllowingUI로 설정하여 [XUserAddAsync](/reference/system/xuser/functions/xuseraddasync)를 반복해서 호출하는 경우에도 개발자가 알아야 할 몇 가지 예외적인 상황이 있습니다. 이 상황들은 자동(무음) UI 경우와 매우 유사(동일하지는 않음)합니다.

* 이 함수를 반복해서 호출할 때 게임을 시작한 기본 사용자를 알고 있는 경우, 동일한 사용자를 반환합니다.
* 이전에 알려진 기본 사용자가 로그아웃했고, 장치에 로그인된 사용자가 한 명뿐인 경우, 해당 사용자를 새 "기본" 사용자로 표시하고 반환합니다.
* 처음 게임을 시작한 사용자가 로그아웃했고, 사용자 수가 0명이거나 두 명 이상인 경우, 시스템이 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;
}
```

## 요구 사항

**헤더:** XUser.h

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

## 함께 보기

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

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

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