XUserAddOptions

사용자 추가 옵션을 지정합니다.

구문

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

상수

상수	설명
None	옵션이 없습니다.
AddDefaultUserSilently	UI를 팝업하지 않고 게임을 시작한 사용자를 가져옵니다.
AllowGuests	게스트는 사용자 선택 UI에 포함됩니다.
AddDefaultUserAllowingUI	게임을 자동으로 시작한 초기 사용자를 가져오려고 합니다. 시스템에서 UI를 표시하지 않고 해당 사용자를 가져올 수 있는 경우에는 이 작업을 시도합니다. 해당 사용자가 동의를 하거나 계정 문제를 해결해야 하는 경우 문제 해결을 위해 UI가 표시됩니다.

설명

개발자가 options를 XUserAddOptions::AddDefaultUserSilently로 설정하여 XUserAddAsync를 반복적으로 호출하는 경우에 알아야 하는 몇 가지 최신 사례가 있습니다.

• 반복적으로 호출하게 되고, 게임을 시작한 기본 사용자가 있다는 사실이 확인되면 동일한 사용자가 반환됩니다.
• 이전에 알려진 기본 사용자가 로그아웃했으며 장치에 로그인한 사용자가 1명 뿐이면 해당 사용자를 새 "기본" 사용자로 표시한 후 반환합니다.
• 이전에 알려진 기본 사용자가 로그아웃했으며 장치에 로그인한 사용자가 여러 명 있으면 E_GAMEUSER_NO_DEFAULT_USER를 반환합니다.
• 개발자 실행에서 기본 사용자가 될 사용자는 자동 로그인 사용자로, DevHome에서 해당 사용자를 자동 로그인 사용자로 설정하거나 xbconfig(NDA 항목)권한 부여 필요 DefaultUser를 사용하여 지정할 수 있습니다.

기본 사용자를 사용할 수 없는 경우 XUserAddResult는 E_GAMEUSER_NO_DEFAULT_USER를 반환합니다. options를 XUserAddOptions::AddDefaultUserSilently로 설정하지 않은 상태로 XUserAddAsync를 호출해야 합니다.

또한 개발자가 options를 XUserAddOptions::AddDefaultUserAllowingUI로 설정하여 XUserAddAsync를 반복적으로 호출하는 경우에 알아야 하는 몇 가지 최신 사례도 있습니다. 이러한 사례는 다음과 같은 자동 UI 사례와 완전히 동일하지는 않지만 매우 유사합니다.

• 반복적으로 호출하게 되고, 게임을 시작한 기본 사용자가 있다는 사실이 확인되면 동일한 사용자가 반환됩니다.
• 이전에 알려진 기본 사용자가 로그아웃했으며 장치에 로그인한 사용자가 1명 뿐이면 해당 사용자를 새 "기본" 사용자로 표시한 후 반환합니다.
• 게임을 처음 시작한 사용자가 로그아웃했으며 사용자 수가 0 이상이면 사용자를 가져온 후 해당 사용자를 기본값으로 설정하기 위해 UI가 표시됩니다.

XUserAddAsync에서 XUserAddOptions::AllowGuests는 XUserAddOptions::AddDefaultUserSilently와 함께 사용할 수 없습니다. 게스트는 기본 사용자일 수 없습니다.

현재 플랫폼에서 게스트를 지원하지 않더라도 XUserAddOptions:: AllowGuests를 사용할 수 있습니다.

다음 예제에서는 게임 세션에 사용자를 비동기적으로 추가하는 방법을 보여줍니다.

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

XUserAddAsync

XUserAddResult