XUserAddAsync

아티클
05/10/2023

사용자를 게임 세션에 비동기적으로 추가합니다.

구문

HRESULT XUserAddAsync(  
         XUserAddOptions options,  
         XAsyncBlock* async  
)

매개 변수

options _In_
형식: XUserAddOptions

사용자를 게임 세션에 추가하는 옵션입니다.

async _Inout_
형식: XAsyncBlock*

호출의 상태를 폴링하고 호출 결과를 검색하기 위해 사용할 수 있는 XAsyncBlock입니다.

반환 값

형식: HRESULT

HRESULT 성공 또는 오류 코드입니다. 오류 코드 목록은 오류 코드를 참조하세요.

비고

XUserAddAsync는 비동기 작업을 시작하여 게임에 사용자를 추가합니다. XUserAddResult를 사용하여 작업 결과를 검색합니다.

XUserAddAsync는 XUserAddOptions::AddDefaultUserSilently 또는 XUserAddOptions::AddDefaultUserAllowingUI가 options 매개 변수에 전달되지 않는 한, 항상 계정 선택기 UI를 표시합니다.

XUserAddOptions::AddDefaultUserSilently를 사용한다면 XUserAddAsync는 UI를 표시하지 않습니다.

단순화된 사용자 모델(NDA 주제)권한 부여 필요을 사용할 때 이 기능에는 몇 가지 고려 사항이 있습니다.

간소화된 사용자 모델을 통해 개발자는 옵션이 XUserAddOptions::AddDefaultUserSilently로 설정되었는지 확인해야 합니다.
콘솔에서 간소화된 사용자 모델을 사용하는 느슨한 배포 게임은 이미 기본 사용자가 로그인되어 있지 않으면 시작할 수 없습니다.
PC에서는 간소화된 사용자 모델을 사용하는 느슨한 배포 게임을 사용자 없이 시작할 수 있습니다. 그러나 게임에서 XUserAddAsync를 호출할 때 아무도 로그인하지 않으면 게임이 종료되고 PC 부트스트래퍼가 시작되어 사용자 로그인에 도움이 됩니다. 사용자가 Xbox Live 완전히 로그인하는 한 후속 실행은 제대로 작동합니다.

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

반복적으로 호출하게 되고, 게임을 시작한 기본 사용자가 있다는 사실이 확인되면 동일한 사용자가 반환됩니다.
이전에 알려진 기본 사용자가 로그아웃했으며 장치에 로그인한 사용자가 1명 뿐이면 해당 사용자를 새 "기본" 사용자로 표시한 후 반환합니다.
이전에 알려진 기본 사용자가 로그아웃했으며 장치에 로그인한 사용자가 여러 명 있으면 E_GAMEUSER_NO_DEFAULT_USER를 반환합니다.

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

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

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

XUserAddOptions::AllowGuests는 XUserAddOptions::AddDefaultUserSilently와 함께 사용할 수 없습니다. 게스트는 기본 사용자일 수 없습니다. XUserAddOptions::AllowGuests는 현재 플랫폼의 게스트 지원 여부에 관계없이 사용할 수 있습니다.

XUsers API에서 검색한 각 XUserHandle 핸들은 XUserCloseHandle을 호출하여 한 번만 닫아야 합니다.

XUserAddAsync가 성공적으로 완료되면 입력 장치 페어링이 수행됩니다. XUserAddOptions::AddDefaultUserSilently 또는 XUserAddOptions::AddDefaultUserAllowingUI 옵션으로 인해 자동으로 로그인이 발생하는 경우 시스템에서 사용자에게 할당된 입력 장치가 제목에 전파됩니다. 로그인에 대한 UI가 표시된 경우 사용자가 선택한 입력 장치가 해당 사용자에게 할당됩니다.

장치 연결은 XUserRegisterForDeviceAssociationChanged 메서드를 통해 추적될 수 있습니다.

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

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;
}