XUserAddResult

아티클
05/09/2023

XUserAddAsync가 생성한 사용자에 대한 핸들을 검색합니다.

구문

HRESULT XUserAddResult(  
         XAsyncBlock* async,  
         XUserHandle* newUser  
)

매개 변수

async _Inout_
형식: XAsyncBlock*

XUserAddAsync로 전송한 비동기 블록입니다.

newUser _Out_
형식: XUserHandle*

새 사용자에 대한 핸들을 포함합니다.

반환 값

형식: HRESULT

HRESULT 성공 또는 오류 코드입니다.

반환 코드	설명
S_OK	작업이 성공했습니다.
E_GAMEUSER_NO_DEFAULT_USER	기본 사용자는 사용할 수 없습니다. XUserAddOptions::AddDefaultUserSilently 없이 XUserAddAsync를 호출해야 합니다.
E_GAMEUSER_RESOLVE_USER_ISSUE_REQUIRED	사용자는 반드시 UI를 사용해 문제를 해결해야 합니다. XUserResolveIssueWithUiAsync를 호출하여 사용자에게 UI를 표시합니다.
E_ABORT	사용자가 작업을 취소했습니다.

비고

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

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

XUserAddOptions::AddDefaultUserSilently를 사용한다면 XUserAddAsync는 UI를 표시하지 않습니다. XUserAddOptions::AddDefaultUserSilently가 반환한 사용자는 사용자가 로그아웃할 때까지 계속 반환됩니다. 기본 사용자를 사용할 수 없다면, XUserAddResult는 E_GAMEUSER_NO_DEFAULT_USER를 반환합니다. 즉 XUserAddAsync를 반드시 호출해야 하고 XUserAddOptions::AddDefaultUserSilently가 사용자를 선택해선 안 됩니다.

사용자가 Xbox Live에서 사용 금지된 경우 게임에서 해당 사용자에 대한 XUserHandle을 가져올 수 없게 됩니다. XUserAddOptions::AddDefaultUserSilently가 사용되고 사용 금지된 사용자가 게임을 실행한 경우 XUserAddResult가 E_GAMEUSER_NO_DEFAULT_USER를 반환합니다. 그러지 않으면 UI가 표시될 경우, 사용이 금지되지 않은 사용자가 로그인해야 합니다. 아니면 해당 사용자가 UI에서 취소해야 합니다. XUserAddResult가 E_ABORT를 반환합니다.

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

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

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

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